@kumwe/studio-testkit 0.1.0-alpha.10

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,138 @@
+# `@kumwe/studio-testkit`
+
+Status: pre-Gate-A foundation alpha. Its conformance helpers do not by themselves constitute gate evidence.
+
+The current alpha combines fixture builders and `assertBlueprintConforms` with deterministic host and HTTP
+testbeds plus executable command, canonical, host, host-sequence, media, preview, property-schema,
+binding-projection, renderer-web, rich-text, and authoring-web corpus runners. Those helpers let another
+implementation replay the same portable assertions without adopting Studio internals. A green repository
+replay is implementation evidence, not an accepted gate or support claim; every advertised profile still
+needs exact-candidate evidence and independent review.
+
+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.
+
+`fixtures/authoring-message-catalog.en.json` is the byte-identical canonical English shell catalog.
+It lets hosts validate localization imports and parameter declarations without importing the Lit
+runtime. Its schema ships with `@kumwe/studio-protocol`.
+
+## Host testbed
+
+`createTestbedHost(options)` builds a deterministic, fully in-memory `HostAdapter` reference host
+for conformance and failure testing. Every standard port is implemented against
+seeded fixtures (`documents`, `resources`, `mediaAssets`, `messages`, `permissions`, and an
+optional asynchronous preview `render` callback). Each operation first validates connectivity and the
+`HostRequestContext`, including exact operation-capability matching, wire protocol, and current session
+generation. Every failure rejects with `TestbedHostError`, whose `error` document satisfies
+`isHostPortError`. `TestbedHostError` extends the protocol's public `HostPortFailure`, so the same
+rejection satisfies `isHostPortFailure` without consumers depending on the testbed-specific class.
+Stale-generation rejection is `invalid-request` with the exact
+`studio.host/stale-session-generation` diagnostic used for whole-handle invalidation; unrelated
+invalid requests do not carry that meaning. `not-found` messages never disclose which identifiers
+exist. Seed artifact kinds, revisions, and the optional initial `sessionGeneration` are retained
+exactly; subsequent 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. The logical
+`advanceClock()` control and declared fixed-window policies make rate-limit tests deterministic.
+Idempotency records use the published scope/preimage, coalesce matching accepted mutations, reject
+changed intent, and remove failed attempts. Preview render controls expose pending and delivered
+outcomes so cancellation proves that late output is discarded. An injected renderer must return the
+originating draft digest and render `requestId`; an uncorrelated result fails as non-retryable
+`internal` and is never recorded as delivered.
+`createHostRequestContextFixture` builds request envelopes; callers provide the exact operation ID for
+strict hosts. The `allowTestOperationId` option permits only the fixture wildcard for broad unit drills,
+defaults off, and must never be enabled for conformance replay. The testbed uses no wall clock,
+randomness, or timers, so runs are fully reproducible.
+
+## Host conformance corpus
+
+`@kumwe/studio-testkit/vectors/host/<filename>` publishes the executable assertion set for
+`studio.profile/host-baseline`. Each vector is language-neutral JSON conforming to
+`host-vector.schema.json`: it fixes the host state to seed (`given`), the request envelope and
+argument to send (`context`, `argument`), and the required outcome (`expect`) — an accepted result
+with its revision behaviour, or one category of the closed error taxonomy with its retry
+classification and non-disclosure obligations. Every precondition is a condition a real host
+reproduces, never a test double, so an adapter written in any language replays the corpus in its own
+test suite without executing Studio code. The reference host's own claim against the profile is
+`test/host-vectors.test.ts`. The profile records the obligations it does not yet assert; consult
+`docs/contracts/conformance-profiles.md` before treating a green replay as complete coverage.
+
+`@kumwe/studio-testkit/vectors/host-sequence/<filename>` publishes the additive assertion set for
+`studio.profile/host-baseline-v2`. The bounded sequence shape expresses pending and settled operations,
+fixed-window policies, explicit clock advances and renderer completions, and final state. Nine vectors
+cover in-flight/completed replay, changed argument/context refusal, canonical numeric intent,
+resource-scope separation, wrong-operation refusal, failed-attempt retry after a window reset, matching
+preview cancellation with late-result discard, and cross-context cancellation isolation. The
+TypeScript replay is `test/host-sequence-vectors.test.ts`; other runtimes consume the same JSON and
+schema directly. The exact assertion list and deliberately recorded limits live in
+`docs/contracts/conformance-profiles.md`.
+
+The host corpus includes `model.get` and `model.list` exchanges over seeded content models. The testbed
+resolves exact ID/version/revision coordinates and lists detached projections in deterministic coordinate
+order. The injected HTTP adapter maps the same operations to `POST /ports/model/get` and
+`POST /ports/model/list`.
+
+`@kumwe/studio-testkit/vectors/canonical/<filename>` publishes the canonical serialization corpus:
+each vector carries a bounded value and either the exact canonical string with the SRI-style digest of
+its UTF-8 bytes, or the stable reason the canonical form refuses it. Its expectations were produced by
+an independent canonicalizer rather than recorded from the reference implementation, so replaying it
+is a cross-implementation check.
+
+`@kumwe/studio-testkit/vectors/preview/<filename>` publishes the executable assertion set for
+`studio.profile/preview-identity-v1`. Each complete Blueprint fixes the lowercase SHA-256 digest of
+its canonical UTF-8 bytes, the artifact/revision/digest render tuple with a unique attempt ID, and the
+exact marker preorder plus one-to-one marker map. The reference replay is
+`test/preview-vectors.test.ts`; another runtime hashes and traverses the same JSON without executing
+Studio code.
+
+`@kumwe/studio-testkit/vectors/schema-profile/<filename>` publishes the executable assertion set for
+`studio.profile/schema-property`. Accepted candidates carry instance verdicts and the first stable
+keyword/pointer diagnostic; rejected candidates carry the closed admission code and schema pointer.
+`runSchemaProfileVector(vector)` replays one vector through the TypeScript reference without consulting
+its expected verdicts or diagnostics. Other runtimes consume the same JSON directly and do not execute
+testkit code. Boundary vectors identify their published limit, exact value, and side of the ceiling;
+the corpus contains exactly one at-limit and one exact-plus-one case for every advertised limit. Its
+acyclic-reference fan-out case must complete without expanding the reference DAG exponentially. The
+TypeScript reference exposes the full ordered set of distinct failures: repeated branches do not
+duplicate an otherwise identical keyword, instance pointer, and message diagnostic.
+Competing-failure vectors also pin one admission order across root invariants, local-reference
+resolution, recursion, and structural keyword checks.
+
+`@kumwe/studio-testkit/vectors/binding-projection/<filename>` publishes
+`studio.profile/binding-projection-v1`. Each vector carries a complete Blueprint, authorized content model,
+block definitions and exact normalized candidate/control/status/diagnostic output.
+`runBindingProjectionVector(vector)` replays one vector without reading its expected result; another runtime
+consumes the same JSON directly. The runner and reference projection never mutate vector input.
+
+`@kumwe/studio-testkit/corpus-manifest.json` carries the sha256 digest of every file in the published
+corpus, grouped by the directory it ships in. A host that vendors the corpus verifies its copy against
+this manifest, so a stale or altered fixture is detected before it silently changes what a conformance
+claim means. The schema manifest in `@kumwe/studio-protocol` covers the schemas; this covers everything
+replayed against them.
+
+`@kumwe/studio-testkit/conformance/authoring-web/<filename>` publishes selector-neutral authoring
+lanes. `runAuthoringWebVector(vector, adapter)` opens a fresh adapter session for every lane, performs
+only the vector actions, and compares the returned canonical document, command intents, focus,
+selection, announcements and dirty state. The adapter is deliberately injected: a browser host maps
+the semantic steps onto its real DOM without exposing Lit, Editor.js, drag-and-drop, or host types in
+the corpus. The current runner test proves fixture isolation and comparison behavior; it is not a
+claim that the production shell has completed the entire authoring-web profile.
+
+`@kumwe/studio-testkit/studio-release.json` is byte-identical to the workspace and protocol copies. A
+host can vendor this record with the corpus, verify `corpusManifestDigest`, and resolve the exact eight
+package versions named by one Studio release coordinate. An empty `claimedProfiles` array is deliberate:
+repository tests and declared targets are not evidence-backed release claims.
+
+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 the applicable Version 2 TypeScript profile. Eight Version 2 profiles are
+declared executable in the repository; `studio.profile/authoring-web` alone remains a target until its complete
+real-shell assertion set and manual matrix exist. None is claimed by the current release record, and this
+foundation alpha must not be cited as accepted gate evidence. Dart/Flutter parity belongs to Version 3.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,9 @@
+# Third-party notices
+
+<!-- Generated by scripts/generate-third-party-notices.mjs. Do not edit by hand. -->
+
+Package: `@kumwe/studio-testkit`
+
+Production closure SHA-256: `4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945`
+
+This package has no third-party runtime dependencies.

package/conformance/authoring-web/non-drag-move-equivalence.json

@@ -0,0 +1,199 @@
+{
+  "contractVersion": "0.1-draft",
+  "kind": "authoring-web-vector",
+  "id": "studio.conformance/non-drag-move-equivalence",
+  "description": "Keyboard, explicit structural control, and pointer enhancement dispatch the same root move while keeping the moved node selected and focused.",
+  "requirements": ["SR-001", "SR-003", "SR-017", "SR-029"],
+  "given": {
+    "document": {
+      "contractVersion": "0.1-draft",
+      "kind": "blueprint",
+      "id": "studio.conformance/authoring-move",
+      "version": "1.0.0",
+      "revision": "authoring-move-r1",
+      "owner": { "id": "studio.conformance/suite", "version": "1.0.0" },
+      "status": "draft",
+      "label": {
+        "key": "studio.conformance/authoring-move-label",
+        "defaultMessage": "Authoring move vector"
+      },
+      "model": {
+        "id": "studio.conformance/model",
+        "version": "1.0.0",
+        "revision": "model-r1"
+      },
+      "dependencyLock": {
+        "theme": {
+          "id": "studio.conformance/theme",
+          "version": "1.0.0",
+          "revision": "theme-r1"
+        },
+        "blocks": [
+          {
+            "type": "studio.core/heading",
+            "version": "1.0.0",
+            "revision": "heading-r1"
+          }
+        ]
+      },
+      "roots": [
+        {
+          "id": "node-first",
+          "type": "studio.core/heading",
+          "version": "1.0.0",
+          "properties": { "level": 2 },
+          "bindings": {
+            "text": {
+              "source": { "kind": "static-value", "value": "First" },
+              "transforms": [],
+              "onNull": "empty",
+              "onError": "error"
+            }
+          },
+          "slots": {},
+          "authoring": { "mode": "content" }
+        },
+        {
+          "id": "node-second",
+          "type": "studio.core/heading",
+          "version": "1.0.0",
+          "properties": { "level": 2 },
+          "bindings": {
+            "text": {
+              "source": { "kind": "static-value", "value": "Second" },
+              "transforms": [],
+              "onNull": "empty",
+              "onError": "error"
+            }
+          },
+          "slots": {},
+          "authoring": { "mode": "content" }
+        }
+      ]
+    },
+    "direction": "ltr",
+    "locale": "en",
+    "readOnly": false,
+    "reducedMotion": false,
+    "selection": "node-first",
+    "viewport": { "height": 900, "width": 1440, "zoomPercent": 100 }
+  },
+  "lanes": [
+    {
+      "name": "keyboard-move-down",
+      "surface": "keyboard",
+      "steps": [
+        { "kind": "focus-node", "nodeId": "node-first", "region": "outline" },
+        {
+          "kind": "key",
+          "key": "ArrowDown",
+          "modifiers": ["Alt"],
+          "region": "outline"
+        }
+      ]
+    },
+    {
+      "name": "explicit-move-control",
+      "surface": "structural-control",
+      "steps": [
+        { "kind": "focus-node", "nodeId": "node-first", "region": "outline" },
+        {
+          "kind": "activate-command",
+          "region": "command-palette",
+          "type": "studio.command/move-node",
+          "payload": { "nodeId": "node-first", "destination": { "position": 1 } }
+        }
+      ]
+    },
+    {
+      "name": "pointer-drag-enhancement",
+      "surface": "pointer",
+      "steps": [
+        { "kind": "focus-node", "nodeId": "node-first", "region": "canvas" },
+        {
+          "kind": "drag-node",
+          "nodeId": "node-first",
+          "destination": { "position": 1 }
+        }
+      ]
+    }
+  ],
+  "expect": {
+    "announcements": [{ "key": "studio.authoring/node-moved", "politeness": "polite" }],
+    "commands": [
+      {
+        "type": "studio.command/move-node",
+        "payload": { "nodeId": "node-first", "destination": { "position": 1 } }
+      }
+    ],
+    "dirty": true,
+    "document": {
+      "contractVersion": "0.1-draft",
+      "kind": "blueprint",
+      "id": "studio.conformance/authoring-move",
+      "version": "1.0.0",
+      "revision": "authoring-move-r1",
+      "owner": { "id": "studio.conformance/suite", "version": "1.0.0" },
+      "status": "draft",
+      "label": {
+        "key": "studio.conformance/authoring-move-label",
+        "defaultMessage": "Authoring move vector"
+      },
+      "model": {
+        "id": "studio.conformance/model",
+        "version": "1.0.0",
+        "revision": "model-r1"
+      },
+      "dependencyLock": {
+        "theme": {
+          "id": "studio.conformance/theme",
+          "version": "1.0.0",
+          "revision": "theme-r1"
+        },
+        "blocks": [
+          {
+            "type": "studio.core/heading",
+            "version": "1.0.0",
+            "revision": "heading-r1"
+          }
+        ]
+      },
+      "roots": [
+        {
+          "id": "node-second",
+          "type": "studio.core/heading",
+          "version": "1.0.0",
+          "properties": { "level": 2 },
+          "bindings": {
+            "text": {
+              "source": { "kind": "static-value", "value": "Second" },
+              "transforms": [],
+              "onNull": "empty",
+              "onError": "error"
+            }
+          },
+          "slots": {},
+          "authoring": { "mode": "content" }
+        },
+        {
+          "id": "node-first",
+          "type": "studio.core/heading",
+          "version": "1.0.0",
+          "properties": { "level": 2 },
+          "bindings": {
+            "text": {
+              "source": { "kind": "static-value", "value": "First" },
+              "transforms": [],
+              "onNull": "empty",
+              "onError": "error"
+            }
+          },
+          "slots": {},
+          "authoring": { "mode": "content" }
+        }
+      ]
+    },
+    "focus": { "region": "outline", "nodeId": "node-first" },
+    "selection": "node-first"
+  }
+}

package/conformance/renderer-web/blob-default-deny.json

@@ -0,0 +1,47 @@
+{
+  "id": "renderer-web/blob-default-deny",
+  "coverage": {
+    "blockTypes": ["studio.core/image"],
+    "behaviors": [],
+    "presentation": [],
+    "security": ["blob-default-deny"]
+  },
+  "roots": [
+    {
+      "authoring": { "mode": "content" },
+      "bindings": {},
+      "id": "blob-default",
+      "properties": { "fit": "cover", "loading": "lazy" },
+      "slots": {},
+      "type": "studio.core/image",
+      "version": "1.0.0"
+    }
+  ],
+  "bindings": [
+    {
+      "nodeId": "blob-default",
+      "port": "asset",
+      "value": {
+        "contractVersion": "0.1-draft",
+        "kind": "media-reference",
+        "assetId": "local",
+        "usage": "studio.media/content",
+        "accessibility": { "mode": "informative", "altText": "Local" }
+      }
+    }
+  ],
+  "media": [
+    {
+      "assetId": "local",
+      "src": "blob:https://studio.example.test/323e4567-e89b-12d3-a456-426614174000",
+      "altText": "Local",
+      "mediaType": "image/png"
+    }
+  ],
+  "expect": {
+    "htmlContains": ["Image unavailable"],
+    "htmlExcludes": ["blob:https://"],
+    "cssContains": ["prefers-reduced-motion"],
+    "enhancements": []
+  }
+}

package/conformance/renderer-web/chart-fallback.json

@@ -0,0 +1,39 @@
+{
+  "id": "renderer-web/chart-fallback",
+  "coverage": {
+    "blockTypes": ["studio.core/chart"],
+    "behaviors": [],
+    "presentation": [],
+    "security": ["typed-data-fallback"]
+  },
+  "roots": [
+    {
+      "authoring": { "mode": "content" },
+      "bindings": {},
+      "id": "chart",
+      "properties": {},
+      "slots": {},
+      "type": "studio.core/chart",
+      "version": "1.0.0"
+    }
+  ],
+  "bindings": [
+    {
+      "nodeId": "chart",
+      "port": "chart",
+      "value": {
+        "type": "bar",
+        "title": "Revenue",
+        "labels": ["Q1", "Q2"],
+        "datasets": [{ "label": "NAD", "values": [10, 20] }]
+      }
+    }
+  ],
+  "media": [],
+  "expect": {
+    "htmlContains": ["<table data-studio-chart-table>", "Revenue", "Q1", "20"],
+    "htmlExcludes": ["<script", "onClick"],
+    "cssContains": ["data-studio-chart-table"],
+    "enhancements": ["chart"]
+  }
+}