From c4f650ce516801a14377ed7fb72d0255761cfb74 Mon Sep 17 00:00:00 2001
From: solidsnakedev <jona.ca.eng@gmail.com>
Date: Fri, 21 Nov 2025 10:05:47 -0700
Subject: [PATCH] feat(docs): improve CBOR decoder tool UI and add data decoder
 option

---
 .../tools/tx-decoder/transaction-decoder.tsx  | 131 +++++++++++++-----
 docs/content/docs/modules/core/CBOR.mdx       |  22 +++
 docs/content/docs/modules/core/Data.mdx       |  37 +++--
 docs/content/docs/modules/core/TSchema.mdx    |  73 +++++++++-
 docs/next-env.d.ts                            |   2 +-
 .../evolution/docs/modules/core/TSchema.ts.md |  16 ++-
 packages/evolution/src/core/index.ts          |   1 +
 7 files changed, 218 insertions(+), 64 deletions(-)

diff --git a/docs/app/tools/tx-decoder/transaction-decoder.tsx b/docs/app/tools/tx-decoder/transaction-decoder.tsx
index c6242661..c3b4bc0e 100644
--- a/docs/app/tools/tx-decoder/transaction-decoder.tsx
+++ b/docs/app/tools/tx-decoder/transaction-decoder.tsx
@@ -1,12 +1,15 @@
 'use client'
 
 import { useState } from 'react'
-import { Core } from "@evolution-sdk/evolution"
+import { Core, Schema } from "@evolution-sdk/evolution"
+
+type DecodeType = 'transaction' | 'witnessSet' | 'data'
 
 export function TransactionDecoder() {
   const [txHex, setTxHex] = useState("")
   const [decodedJson, setDecodedJson] = useState<string>("")
   const [error, setError] = useState<string | null>(null)
+  const [decodeType, setDecodeType] = useState<DecodeType>('transaction')
 
   const decodeTx = async () => {
     setError(null)
@@ -16,60 +19,114 @@ export function TransactionDecoder() {
       const cleanHex = txHex.trim().replace(/\s+/g, '')
       
       if (!cleanHex) {
-        setError("Please enter a transaction CBOR hex string")
+        setError(`Please enter a ${decodeType === 'transaction' ? 'transaction' : decodeType === 'witnessSet' ? 'transaction witness set' : 'plutus data'} CBOR hex string`)
         return
       }
       
-      const tx = Core.Transaction.fromCBORHex(cleanHex)
-      const json = JSON.stringify(tx.toJSON(), (key, value) =>
-        typeof value === 'bigint' ? value.toString() : value
-      , 2)
-      setDecodedJson(json)
+      if (decodeType === 'transaction') {
+        const tx = Core.Transaction.fromCBORHex(cleanHex)
+        const json = Schema.encodeSync(Schema.parseJson(Core.Transaction.Transaction, {space: 2}))(tx)
+        setDecodedJson(json)
+      } else if (decodeType === 'witnessSet') {
+        const witnessSet = Core.TransactionWitnessSet.fromCBORHex(cleanHex)
+        const json = Schema.encodeSync(Schema.parseJson(Core.TransactionWitnessSet.TransactionWitnessSet, {space: 2}))(witnessSet)
+        setDecodedJson(json)
+      } else {
+        const data = Core.Data.fromCBORHex(cleanHex)
+        const json = Schema.encodeSync(Schema.parseJson(Core.Data.DataSchema, {space: 2}))(data)
+        setDecodedJson(json)
+      }
     } catch (err) {
       console.error('Decode error:', err)
-      setError(err instanceof Error ? err.message : "Failed to decode transaction")
+      setError(err instanceof Error ? err.message : `Failed to decode ${decodeType === 'transaction' ? 'transaction' : decodeType === 'witnessSet' ? 'witness set' : 'data'}`)
     }
   }
 
   return (
-    <div className="space-y-6">
-      <div className="space-y-4">
-        <button
-          onClick={decodeTx}
-          className="px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary/90 transition-colors"
-        >
-          Decode Transaction
-        </button>
-
-        <div className="space-y-2">
-          <label htmlFor="tx-hex" className="block text-sm font-medium">
-            Transaction CBOR Hex
-          </label>
-          <textarea
-            id="tx-hex"
-            value={txHex}
-            onChange={(e) => setTxHex(e.target.value)}
-            placeholder="Paste transaction CBOR hex here..."
-            className="w-full h-32 px-3 py-2 bg-background border border-border rounded-md font-mono text-sm resize-y focus:outline-none focus:ring-2 focus:ring-ring"
-          />
+    <div className="max-w-6xl mx-auto space-y-6">
+      <div className="rounded-lg border bg-card text-card-foreground shadow-sm">
+        <div className="p-6 space-y-6">
+          <div className="flex items-center justify-between">
+            <div className="space-y-1">
+              <h3 className="text-2xl font-semibold tracking-tight">CBOR Decoder</h3>
+              <p className="text-sm text-muted-foreground">Decode Cardano CBOR hex strings</p>
+            </div>
+          </div>
+          
+          <div className="space-y-4">
+            <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+              <div className="space-y-2">
+                <label htmlFor="decode-type" className="text-sm font-medium leading-none">
+                  Type
+                </label>
+                <select
+                  id="decode-type"
+                  value={decodeType}
+                  onChange={(e) => setDecodeType(e.target.value as DecodeType)}
+                  className="flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-ring"
+                >
+                  <option value="transaction">Transaction</option>
+                  <option value="witnessSet">Transaction Witness Set</option>
+                  <option value="data">Plutus Data</option>
+                </select>
+              </div>
+            </div>
+            
+            <div className="space-y-2">
+              <label htmlFor="tx-hex" className="text-sm font-medium leading-none">
+                CBOR Hex Input
+              </label>
+              <textarea
+                id="tx-hex"
+                value={txHex}
+                onChange={(e) => setTxHex(e.target.value)}
+                placeholder={`Paste ${decodeType === 'transaction' ? 'transaction' : decodeType === 'witnessSet' ? 'transaction witness set' : 'plutus data'} CBOR hex here...`}
+                className="flex min-h-[120px] w-full rounded-md border border-input bg-background px-3 py-2 text-sm font-mono resize-y focus:outline-none focus:ring-2 focus:ring-ring"
+              />
+            </div>
+            
+            <button
+              onClick={decodeTx}
+              className="sm:w-auto w-full inline-flex items-center justify-center rounded-md text-sm font-medium h-9 px-6 py-2 bg-zinc-700 text-white hover:bg-zinc-600 active:bg-zinc-500 transition-all cursor-pointer shadow-sm hover:shadow"
+            >
+              Decode {decodeType === 'transaction' ? 'Transaction' : decodeType === 'witnessSet' ? 'Witness Set' : 'Data'}
+            </button>
+          </div>
         </div>
       </div>
 
       {error && (
-        <div className="p-4 bg-destructive/10 border border-destructive/20 rounded-md">
-          <p className="text-destructive font-medium">Error decoding transaction:</p>
-          <p className="text-destructive/80 text-sm mt-1">{error}</p>
+        <div className="rounded-lg border bg-card text-card-foreground shadow-sm">
+          <div className="p-6">
+            <div className="flex gap-3">
+              <svg className="h-5 w-5 text-destructive shrink-0 mt-0.5" viewBox="0 0 20 20" fill="currentColor">
+                <path fillRule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zM8.707 7.293a1 1 0 00-1.414 1.414L8.586 10l-1.293 1.293a1 1 0 101.414 1.414L10 11.414l1.293 1.293a1 1 0 001.414-1.414L11.414 10l1.293-1.293a1 1 0 00-1.414-1.414L10 8.586 8.707 7.293z" clipRule="evenodd" />
+              </svg>
+              <div className="flex-1 min-w-0 space-y-2">
+                <p className="text-sm font-medium text-destructive">Error decoding {decodeType === 'transaction' ? 'transaction' : decodeType === 'witnessSet' ? 'witness set' : 'data'}</p>
+                <pre className="text-xs text-muted-foreground whitespace-pre-wrap break-words overflow-wrap-anywhere font-mono">{error}</pre>
+              </div>
+            </div>
+          </div>
         </div>
       )}
-
+      
       {decodedJson && (
-        <div className="space-y-2">
-          <label className="block text-sm font-medium">Decoded Transaction (JSON)</label>
-          <pre className="w-full p-4 bg-muted border border-border rounded-md overflow-auto max-h-[600px] text-sm">
-            <code>{decodedJson}</code>
-          </pre>
+        <div className="rounded-lg border bg-card text-card-foreground shadow-sm">
+          <div className="p-6 space-y-3">
+            <h4 className="text-sm font-semibold">Decoded Result</h4>
+            <pre className="rounded-md bg-muted p-4 overflow-x-auto max-h-[500px]">
+              <code className="text-xs">{decodedJson}</code>
+            </pre>
+          </div>
         </div>
       )}
+
+      <div className="pt-4 border-t border-border/50">
+        <p className="text-xs text-center text-muted-foreground">
+          Questions or feedback? <a href="https://github.com/IntersectMBO/evolution-sdk/issues" target="_blank" rel="noopener noreferrer" className="text-primary hover:underline">Start a discussion on GitHub</a>
+        </p>
+      </div>
     </div>
   )
 }
diff --git a/docs/content/docs/modules/core/CBOR.mdx b/docs/content/docs/modules/core/CBOR.mdx
index 217ef724..ee076594 100644
--- a/docs/content/docs/modules/core/CBOR.mdx
+++ b/docs/content/docs/modules/core/CBOR.mdx
@@ -11,6 +11,7 @@ parent: Modules
 <h2 className="text-delta">Table of contents</h2>
 
 - [constants](#constants)
+  - [AIKEN_DEFAULT_OPTIONS](#aiken_default_options)
   - [CANONICAL_OPTIONS](#canonical_options)
   - [CBOR_ADDITIONAL_INFO](#cbor_additional_info)
   - [CBOR_MAJOR_TYPE](#cbor_major_type)
@@ -64,6 +65,25 @@ parent: Modules
 
 # constants
 
+## AIKEN_DEFAULT_OPTIONS
+
+Aiken-compatible CBOR encoding options
+
+Matches the encoding used by Aiken's cbor.serialise():
+
+- Indefinite-length arrays (9f...ff)
+- Maps encoded as arrays of pairs (not CBOR maps)
+- Strings as bytearrays (major type 2, not 3)
+- Constructor tags: 121-127 for indices 0-6, then 1280+ for 7+
+
+**Signature**
+
+```ts
+export declare const AIKEN_DEFAULT_OPTIONS: CodecOptions
+```
+
+Added in v2.0.0
+
 ## CANONICAL_OPTIONS
 
 Canonical CBOR encoding options (RFC 8949 Section 4.2.1)
@@ -239,6 +259,7 @@ export type CodecOptions =
   | {
       readonly mode: "canonical"
       readonly mapsAsObjects?: boolean
+      readonly encodeMapAsPairs?: boolean
     }
   | {
       readonly mode: "custom"
@@ -248,6 +269,7 @@ export type CodecOptions =
       readonly sortMapKeys: boolean
       readonly useMinimalEncoding: boolean
       readonly mapsAsObjects?: boolean
+      readonly encodeMapAsPairs?: boolean
     }
 ```
 
diff --git a/docs/content/docs/modules/core/Data.mdx b/docs/content/docs/modules/core/Data.mdx
index b6f55800..0238a07e 100644
--- a/docs/content/docs/modules/core/Data.mdx
+++ b/docs/content/docs/modules/core/Data.mdx
@@ -20,8 +20,6 @@ parent: Modules
   - [int](#int)
   - [list](#list)
   - [map](#map)
-- [either](#either)
-  - [Either (namespace)](#either-namespace)
 - [equality](#equality)
   - [equals](#equals)
   - [hash](#hash)
@@ -71,6 +69,7 @@ parent: Modules
 - [utils](#utils)
   - [ByteArray (type alias)](#bytearray-type-alias)
   - [CDDLSchema](#cddlschema)
+  - [DataSchema (interface)](#dataschema-interface)
   - [Int (type alias)](#int-type-alias)
 
 ---
@@ -88,12 +87,12 @@ export declare const withSchema: <A, I extends Data>(
   schema: Schema.Schema<A, I>,
   options?: CBOR.CodecOptions
 ) => {
-  toData: (input: A) => I
-  fromData: (input: I) => A
-  toCBORHex: (input: A, options?: CBOR.CodecOptions) => string
-  toCBORBytes: (input: A, options?: CBOR.CodecOptions) => Uint8Array
-  fromCBORHex: (hex: string, options?: CBOR.CodecOptions) => A
-  fromCBORBytes: (bytes: Uint8Array, options?: CBOR.CodecOptions) => A
+  toData: (a: A, overrideOptions?: ParseOptions) => I
+  fromData: (i: I, overrideOptions?: ParseOptions) => A
+  toCBORHex: (a: A, overrideOptions?: ParseOptions) => string
+  toCBORBytes: (a: A, overrideOptions?: ParseOptions) => any
+  fromCBORHex: (i: string, overrideOptions?: ParseOptions) => A
+  fromCBORBytes: (i: any, overrideOptions?: ParseOptions) => A
 }
 ```
 
@@ -175,14 +174,6 @@ export declare const map: (entries: Array<[key: Data, value: Data]>) => Map
 
 Added in v2.0.0
 
-# either
-
-## Either (namespace)
-
-Either-based variants for functions that can fail.
-
-Added in v2.0.0
-
 # equality
 
 ## equals
@@ -525,7 +516,7 @@ Combined schema for PlutusData type with proper recursion
 **Signature**
 
 ```ts
-export declare const DataSchema: Schema.Schema<Data, DataEncoded, never>
+export declare const DataSchema: DataSchema
 ```
 
 Added in v2.0.0
@@ -735,7 +726,7 @@ Encode PlutusData to CBOR bytes
 **Signature**
 
 ```ts
-export declare const toCBORBytes: (input: Data, options?: CBOR.CodecOptions) => Uint8Array
+export declare const toCBORBytes: (data: Data, options?: CBOR.CodecOptions) => any
 ```
 
 Added in v2.0.0
@@ -747,7 +738,7 @@ Encode PlutusData to CBOR hex string
 **Signature**
 
 ```ts
-export declare const toCBORHex: (input: Data, options?: CBOR.CodecOptions) => string
+export declare const toCBORHex: (data: Data, options?: CBOR.CodecOptions) => string
 ```
 
 Added in v2.0.0
@@ -808,6 +799,14 @@ export type ByteArray = typeof ByteArray.Type
 export declare const CDDLSchema: Schema.Schema<CBOR.CBOR, CBOR.CBOR, never>
 ```
 
+## DataSchema (interface)
+
+**Signature**
+
+```ts
+export interface DataSchema extends Schema.SchemaClass<Data, DataEncoded> {}
+```
+
 ## Int (type alias)
 
 **Signature**
diff --git a/docs/content/docs/modules/core/TSchema.mdx b/docs/content/docs/modules/core/TSchema.mdx
index b4b1056f..3a9c23fb 100644
--- a/docs/content/docs/modules/core/TSchema.mdx
+++ b/docs/content/docs/modules/core/TSchema.mdx
@@ -12,6 +12,9 @@ parent: Modules
 
 - [combinators](#combinators)
   - [equivalence](#equivalence)
+- [constructors](#constructors)
+  - [TaggedStruct](#taggedstruct)
+  - [Variant](#variant)
 - [schemas](#schemas)
   - [ByteArray](#bytearray)
   - [Integer](#integer)
@@ -62,6 +65,48 @@ export declare const equivalence: <A, I, R>(schema: Schema.Schema<A, I, R>) => E
 
 Added in v2.0.0
 
+# constructors
+
+## TaggedStruct
+
+Creates a tagged struct - a shortcut for creating a Struct with a Literal tag field.
+
+This is a convenience helper that makes it easy to create structs with discriminator fields,
+commonly used in discriminated unions.
+
+**Signature**
+
+```ts
+export declare const TaggedStruct: <
+  TagValue extends string,
+  Fields extends Schema.Struct.Fields,
+  TagField extends string = "_tag"
+>(
+  tagValue: TagValue,
+  fields: Fields,
+  options?: StructOptions & { tagField?: TagField }
+) => Struct<{ [K in TagField]: OneLiteral<TagValue> } & Fields>
+```
+
+Added in v2.0.0
+
+## Variant
+
+Creates a variant (tagged union) schema for Aiken-style enum types.
+
+This is a convenience helper that creates properly discriminated TypeScript types
+while maintaining single-level CBOR encoding compatible with Aiken.
+
+**Signature**
+
+```ts
+export declare const Variant: <Variants extends Record<string, Schema.Struct.Fields>>(
+  variants: Variants
+) => Schema.Schema<VariantType<Variants>, Data.Data, never>
+```
+
+Added in v2.0.0
+
 # schemas
 
 ## ByteArray
@@ -289,7 +334,31 @@ export interface StructOptions {
    *
    * Default: true when index is specified, false otherwise
    */
-  flat?: boolean
+  flatInUnion?: boolean
+  /**
+   * When used as a field in a parent Struct, controls whether this Struct's fields
+   * should be spread (merged) into the parent's field array.
+   * - true: Inner Struct fields are merged directly into parent
+   * - false: Inner Struct is kept as a nested Constr
+   *
+   * Default: false
+   *
+   * Note: This only applies when the Struct is a field value, not when used in Union.
+   */
+  flatFields?: boolean
+  /**
+   * Name of a field to treat as a discriminant tag (e.g., "_tag", "type").
+   *
+   * Auto-detection: Fields named "_tag", "type", "kind", or "variant" containing
+   * Literal values are automatically stripped from CBOR encoding and injected during decoding.
+   *
+   * This option allows you to:
+   * - Explicitly specify a custom tag field name
+   * - Disable auto-detection with `tagField: false`
+   *
+   * Default: auto-detect from KNOWN_TAG_FIELDS
+   */
+  tagField?: string | false
 }
 ```
 
@@ -362,7 +431,7 @@ Added in v2.0.0
 export interface Union<Members extends ReadonlyArray<Schema.Schema.Any>>
   extends Schema.transformOrFail<
     Schema.SchemaClass<Data.Constr, Data.Constr, never>,
-    Schema.SchemaClass<Schema.Schema.Type<[...Members][number]>, Schema.Schema.Type<[...Members][number]>, never>,
+    Schema.SchemaClass<Schema.Schema.Type<Members[number]>, Schema.Schema.Type<Members[number]>, never>,
     never
   > {}
 ```
diff --git a/docs/next-env.d.ts b/docs/next-env.d.ts
index 9edff1c7..24c7c901 100644
--- a/docs/next-env.d.ts
+++ b/docs/next-env.d.ts
@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
+import "./out/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
diff --git a/packages/evolution/docs/modules/core/TSchema.ts.md b/packages/evolution/docs/modules/core/TSchema.ts.md
index 6f3600c0..edd50917 100644
--- a/packages/evolution/docs/modules/core/TSchema.ts.md
+++ b/packages/evolution/docs/modules/core/TSchema.ts.md
@@ -100,9 +100,15 @@ while maintaining single-level CBOR encoding compatible with Aiken.
 **Signature**
 
 ```ts
-export declare const Variant: <Variants extends Record<string, Schema.Struct.Fields>>(
+export declare function Variant<const Variants extends Record<PropertyKey, Schema.Struct.Fields>>(
   variants: Variants
-) => Schema.Schema<VariantType<Variants>, Data.Data, never>
+): Union<
+  ReadonlyArray<
+    {
+      [K in keyof Variants]: Struct<{ readonly [P in K]: Struct<Variants[K]> }>
+    }[keyof Variants]
+  >
+>
 ```
 
 Added in v2.0.0
@@ -297,10 +303,10 @@ Objects are represented as a constructor with index (default 0) and fields as an
 **Signature**
 
 ```ts
-export declare const Struct: <Fields extends Schema.Struct.Fields>(
+export declare function Struct<Fields extends Schema.Struct.Fields>(
   fields: Fields,
-  options?: StructOptions
-) => Struct<Fields>
+  options: StructOptions = {}
+): Struct<Fields>
 ```
 
 Added in v2.0.0
diff --git a/packages/evolution/src/core/index.ts b/packages/evolution/src/core/index.ts
index e3748f07..8dcb96b4 100644
--- a/packages/evolution/src/core/index.ts
+++ b/packages/evolution/src/core/index.ts
@@ -101,6 +101,7 @@ export * as TransactionInput from "./TransactionInput.js"
 export * as TransactionMetadatum from "./TransactionMetadatum.js"
 export * as TransactionMetadatumLabels from "./TransactionMetadatumLabels.js"
 export * as TransactionOutput from "./TransactionOutput.js"
+export * as TransactionWitnessSet from "./TransactionWitnessSet.js"
 export * as TSchema from "./TSchema.js"
 export * as UnitInterval from "./UnitInterval.js"
 export * as Url from "./Url.js"