@kumwe/studio-testkit 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kumwe Studio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# `@kumwe/studio-testkit`
+
+Status: pre-Gate-A foundation alpha. Its conformance helpers do not by themselves constitute gate evidence.
+
+The current alpha exports three builders—`createBlueprintFixture`, `defineTestBlock`, and
+`createStudioConfigurationFixture`—plus `assertBlueprintConforms` and its structured
+`StudioConformanceError`. The assertion checks a Blueprint against supplied block definitions through
+the current core validator. It does not yet prove host, plugin, theme, preview, media, accessibility,
+security, lifecycle, or cross-language conformance.
+
+Package subpaths under `@kumwe/studio-testkit/fixtures/<filename>` contain byte-identical copies of the
+canonical valid examples, including separate MediaAsset and persisted MediaReference examples. There
+is no aggregate runtime `fixtures` export. The helpers do not depend on Vitest or another test runner,
+so consumers may call the current assertion from any JavaScript test environment.
+
+## Host testbed
+
+`createTestbedHost(options)` builds a deterministic, fully in-memory `HostAdapter` reference host
+for conformance and failure testing. Every standard port except `model` is implemented against
+seeded fixtures (`documents`, `resources`, `mediaAssets`, `messages`, `permissions`, and an
+optional preview `render` callback). Each operation first checks connectivity and injected
+failures, then validates the `HostRequestContext` envelope structurally (wrong wire protocol
+versions reject as `incompatible`), then enforces the current session generation. Every failure
+rejects with `TestbedHostError`, whose `error` document satisfies `isHostPortError`; `not-found`
+messages never disclose which identifiers exist. Revisions advance as deterministic counters
+(`<id>-r<n>`), optimistic-concurrency conflicts return the safe current revision without changing
+stored state, and search/media pagination uses opaque cursors. The returned `controls` drive
+failure scenarios: `disconnect()`/`reconnect()` for retryable `unavailable` outages,
+`failNext(port, operation, category)` for exactly one injected failure (retryable only for
+`unavailable` and `rate-limited`), and `setPermissions(...)`, which replaces the permission list
+and bumps the session generation so stale contexts reject as `invalid-request`. `revisionOf(id)`,
+the `sessionGeneration` getter, and the recorded `telemetryEvents` support assertions.
+`createHostRequestContextFixture` builds conforming request envelopes. The testbed uses no clocks,
+randomness, or timers, so runs are fully reproducible.
+
+Gate A requires valid and invalid fixture corpora plus runner-neutral assertions for block, theme,
+plugin, host-port, command, preview, media, compatibility, migration, lifecycle, security,
+accessibility, localization, and TypeScript/Dart equivalence. Those remain target deliverables; this
+foundation alpha must not be cited as their evidence.

package/conformance/rich-text/blocks.structural.json

@@ -0,0 +1,57 @@
+{
+  "description": "Blockquotes and ordered lists flatten to their leaf blocks, a horizontal rule projects as an empty leaf block, and adjacent text nodes with an identical mark set merge into one span.",
+  "document": {
+    "type": "doc",
+    "content": [
+      {
+        "type": "blockquote",
+        "content": [
+          {
+            "type": "paragraph",
+            "content": [
+              { "type": "text", "text": "Quoted " },
+              { "type": "text", "text": "wis", "marks": [{ "type": "bold" }] },
+              { "type": "text", "text": "dom", "marks": [{ "type": "bold" }] }
+            ]
+          }
+        ]
+      },
+      { "type": "horizontalRule" },
+      {
+        "type": "orderedList",
+        "attrs": { "start": 3 },
+        "content": [
+          {
+            "type": "listItem",
+            "content": [
+              {
+                "type": "paragraph",
+                "content": [{ "type": "text", "text": "Third step first." }]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  "projection": [
+    {
+      "type": "paragraph",
+      "text": "Quoted wisdom",
+      "spans": [{ "start": 7, "end": 13, "marks": ["bold"] }],
+      "embeds": []
+    },
+    {
+      "type": "horizontalRule",
+      "text": "",
+      "spans": [],
+      "embeds": []
+    },
+    {
+      "type": "paragraph",
+      "text": "Third step first.",
+      "spans": [],
+      "embeds": []
+    }
+  ]
+}

package/conformance/rich-text/document.multi-block.json

@@ -0,0 +1,74 @@
+{
+  "description": "A heading, a paragraph, and a bullet list flatten to leaf block projections in document order; list containers contribute no entries of their own.",
+  "document": {
+    "type": "doc",
+    "content": [
+      {
+        "type": "heading",
+        "attrs": { "level": 2 },
+        "content": [{ "type": "text", "text": "Care guide" }]
+      },
+      {
+        "type": "paragraph",
+        "content": [
+          { "type": "text", "text": "Wash with " },
+          { "type": "text", "text": "cold water", "marks": [{ "type": "bold" }] },
+          { "type": "text", "text": " only." }
+        ]
+      },
+      {
+        "type": "bulletList",
+        "content": [
+          {
+            "type": "listItem",
+            "content": [
+              {
+                "type": "paragraph",
+                "content": [{ "type": "text", "text": "Empty all pockets." }]
+              }
+            ]
+          },
+          {
+            "type": "listItem",
+            "content": [
+              {
+                "type": "paragraph",
+                "content": [
+                  { "type": "text", "text": "Brush off " },
+                  { "type": "text", "text": "dry mud", "marks": [{ "type": "italic" }] },
+                  { "type": "text", "text": "." }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  "projection": [
+    {
+      "type": "heading",
+      "text": "Care guide",
+      "spans": [],
+      "embeds": []
+    },
+    {
+      "type": "paragraph",
+      "text": "Wash with cold water only.",
+      "spans": [{ "start": 10, "end": 20, "marks": ["bold"] }],
+      "embeds": []
+    },
+    {
+      "type": "paragraph",
+      "text": "Empty all pockets.",
+      "spans": [],
+      "embeds": []
+    },
+    {
+      "type": "paragraph",
+      "text": "Brush off dry mud.",
+      "spans": [{ "start": 10, "end": 17, "marks": ["italic"] }],
+      "embeds": []
+    }
+  ]
+}

package/conformance/rich-text/embed.hard-break.json

@@ -0,0 +1,24 @@
+{
+  "description": "A hard break is the portable inline embed: it contributes no characters, anchors at its code-point offset, and does not interrupt a span whose mark set continues across it.",
+  "document": {
+    "type": "doc",
+    "content": [
+      {
+        "type": "paragraph",
+        "content": [
+          { "type": "text", "text": "first line", "marks": [{ "type": "italic" }] },
+          { "type": "hardBreak" },
+          { "type": "text", "text": "second line", "marks": [{ "type": "italic" }] }
+        ]
+      }
+    ]
+  },
+  "projection": [
+    {
+      "type": "paragraph",
+      "text": "first linesecond line",
+      "spans": [{ "start": 0, "end": 21, "marks": ["italic"] }],
+      "embeds": [{ "index": 10, "kind": "hardBreak" }]
+    }
+  ]
+}

package/conformance/rich-text/marks.nested.json

@@ -0,0 +1,29 @@
+{
+  "description": "Nested marks (bold inside an italic run) project to maximal runs whose mark names are sorted lexicographically regardless of the document's mark order, and spans are sorted by (start, end, marks).",
+  "document": {
+    "type": "doc",
+    "content": [
+      {
+        "type": "paragraph",
+        "content": [
+          { "type": "text", "text": "The ", "marks": [{ "type": "italic" }] },
+          { "type": "text", "text": "quick", "marks": [{ "type": "italic" }, { "type": "bold" }] },
+          { "type": "text", "text": " fox", "marks": [{ "type": "italic" }] },
+          { "type": "text", "text": " runs." }
+        ]
+      }
+    ]
+  },
+  "projection": [
+    {
+      "type": "paragraph",
+      "text": "The quick fox runs.",
+      "spans": [
+        { "start": 0, "end": 4, "marks": ["italic"] },
+        { "start": 4, "end": 9, "marks": ["bold", "italic"] },
+        { "start": 9, "end": 13, "marks": ["italic"] }
+      ],
+      "embeds": []
+    }
+  ]
+}

package/conformance/rich-text/offsets.astral.json

@@ -0,0 +1,24 @@
+{
+  "description": "Astral-plane characters count as one position each: every offset is a Unicode code-point index, never a UTF-16 code-unit or byte index.",
+  "document": {
+    "type": "doc",
+    "content": [
+      {
+        "type": "paragraph",
+        "content": [
+          { "type": "text", "text": "𝄞𝄞 " },
+          { "type": "text", "text": "G🎼clef", "marks": [{ "type": "bold" }] },
+          { "type": "text", "text": " coda𐐷" }
+        ]
+      }
+    ]
+  },
+  "projection": [
+    {
+      "type": "paragraph",
+      "text": "𝄞𝄞 G🎼clef coda𐐷",
+      "spans": [{ "start": 3, "end": 9, "marks": ["bold"] }],
+      "embeds": []
+    }
+  ]
+}

package/conformance/rich-text/paragraph.plain.json

@@ -0,0 +1,20 @@
+{
+  "description": "A single plain paragraph projects to one block with its text, no spans, and no embeds.",
+  "document": {
+    "type": "doc",
+    "content": [
+      {
+        "type": "paragraph",
+        "content": [{ "type": "text", "text": "Portable text stays plain." }]
+      }
+    ]
+  },
+  "projection": [
+    {
+      "type": "paragraph",
+      "text": "Portable text stays plain.",
+      "spans": [],
+      "embeds": []
+    }
+  ]
+}

package/conformance/rich-text/spans.adjacent.json

@@ -0,0 +1,27 @@
+{
+  "description": "Adjacent but non-overlapping marks produce separate half-open spans that share a boundary offset: the first span's exclusive end equals the next span's inclusive start.",
+  "document": {
+    "type": "doc",
+    "content": [
+      {
+        "type": "paragraph",
+        "content": [
+          { "type": "text", "text": "alpha", "marks": [{ "type": "bold" }] },
+          { "type": "text", "text": "beta", "marks": [{ "type": "italic" }] },
+          { "type": "text", "text": " tail" }
+        ]
+      }
+    ]
+  },
+  "projection": [
+    {
+      "type": "paragraph",
+      "text": "alphabeta tail",
+      "spans": [
+        { "start": 0, "end": 5, "marks": ["bold"] },
+        { "start": 5, "end": 9, "marks": ["italic"] }
+      ],
+      "embeds": []
+    }
+  ]
+}

package/dist/host-testbed.d.ts

@@ -0,0 +1,40 @@
+import { type HostAdapter, type HostErrorCategory, type HostPortError, type HostRequestContext, type MediaAsset, type PreviewRenderPayload, type PreviewRenderedPayload, type QualifiedName, type ResourceSearchHit, type Revision, type StableId, type StudioArtifact, type StudioWireProtocolVersion, type TelemetryEvent } from '@kumwe/studio-protocol';
+export type TestbedPortName = 'artifact' | 'localization' | 'media' | 'permission' | 'preview' | 'recovery' | 'resource' | 'telemetry';
+export interface TestbedHostOptions {
+    documents?: StudioArtifact[];
+    mediaAssets?: MediaAsset[];
+    messages?: Record<string, Record<QualifiedName, string>>;
+    permissions?: QualifiedName[];
+    render?: (payload: PreviewRenderPayload) => PreviewRenderedPayload;
+    resources?: ResourceSearchHit[];
+}
+export interface TestbedControls {
+    disconnect(): void;
+    failNext(portName: TestbedPortName, operation: string, category: HostErrorCategory): void;
+    reconnect(): void;
+    revisionOf(id: StableId): Revision | undefined;
+    readonly sessionGeneration: Revision;
+    setPermissions(permissions: QualifiedName[]): void;
+    readonly telemetryEvents: readonly TelemetryEvent[];
+}
+export interface TestbedHost {
+    controls: TestbedControls;
+    host: HostAdapter;
+}
+export interface HostRequestContextFixtureOptions {
+    expectedRevision?: Revision;
+    idempotencyKey?: StableId;
+    locale?: string;
+    operationId?: QualifiedName;
+    protocolVersion?: StudioWireProtocolVersion;
+    requestId?: StableId;
+    resourceContextKey?: StableId;
+    sessionGeneration?: Revision;
+}
+export declare class TestbedHostError extends Error {
+    readonly error: HostPortError;
+    constructor(error: HostPortError);
+}
+export declare function createHostRequestContextFixture(options?: HostRequestContextFixtureOptions): HostRequestContext;
+export declare function createTestbedHost(options?: TestbedHostOptions): TestbedHost;
+//# sourceMappingURL=host-testbed.d.ts.map

package/dist/host-testbed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-testbed.d.ts","sourceRoot":"","sources":["../src/host-testbed.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAElB,KAAK,kBAAkB,EAGvB,KAAK,UAAU,EAEf,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,yBAAyB,EAC9B,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,cAAc,GACd,OAAO,GACP,YAAY,GACZ,SAAS,GACT,UAAU,GACV,UAAU,GACV,WAAW,CAAC;AAEhB,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;IACzD,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;IAC9B,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,sBAAsB,CAAC;IACnE,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,IAAI,IAAI,CAAC;IACnB,QAAQ,CAAC,QAAQ,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1F,SAAS,IAAI,IAAI,CAAC;IAClB,UAAU,CAAC,EAAE,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC;IACrC,cAAc,CAAC,WAAW,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAC;CACrD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,gCAAgC;IAC/C,gBAAgB,CAAC,EAAE,QAAQ,CAAC;IAC5B,cAAc,CAAC,EAAE,QAAQ,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,eAAe,CAAC,EAAE,yBAAyB,CAAC;IAC5C,SAAS,CAAC,EAAE,QAAQ,CAAC;IACrB,kBAAkB,CAAC,EAAE,QAAQ,CAAC;IAC9B,iBAAiB,CAAC,EAAE,QAAQ,CAAC;CAC9B;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAgB,KAAK,EAAE,aAAa,CAAC;gBAElB,KAAK,EAAE,aAAa;CAKxC;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,GAAE,gCAAqC,GAC7C,kBAAkB,CAapB;AAED,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAuW/E"}