@kohaku-ui/renderer-wc 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,141 @@
 # @kohaku-ui/renderer-wc
 
+## 0.4.1
+
+### Patch Changes
+
+- [#64](https://github.com/yosuque/kohaku/pull/64) [`b1a7af7`](https://github.com/yosuque/kohaku/commit/b1a7af7f39f09f2f088298098eaae618b32e363e) Thanks [@yosuque](https://github.com/yosuque)! - `implement` and `implementWc` parse a node's props against the part's schema once per `node.props` object instead of on every render or rebuild, and emit the dev-mode schema-mismatch warning once per props object (design.md decision 68). Rendered output is unchanged.
+
+- [#66](https://github.com/yosuque/kohaku/pull/66) [`0a2a43b`](https://github.com/yosuque/kohaku/commit/0a2a43b5ea0cbe90df1bbe53af9137452654e477) Thanks [@yosuque](https://github.com/yosuque)! - `action.button` and `presentForm` now show the governed-action phases that stop an action before it commits: a rejected payload (`invalid`, `role="alert"`) and a declined confirmation or pending approval (`awaitingApproval`, `role="status"`). renderer-core adds `actionPhaseNotice` and the `RendererMessages.actionInvalid` / `actionAwaiting` strings (design.md decisions 62-64); `<kohaku-surface>` also clears a form's previous submit message when a new submit starts, as the React form does.
+
+- [#66](https://github.com/yosuque/kohaku/pull/66) [`4072ca8`](https://github.com/yosuque/kohaku/commit/4072ca8c86f28c2bb79abbfc0483b2e6242b7768) Thanks [@yosuque](https://github.com/yosuque)! - Editable `presentSpreadsheet` cells now run the governed-action pre-check in both renderers (a value the `actionManifest` rejects stays in edit mode with `aria-invalid`), and an optimistic cell edit is discarded again when its `cellEdit` invoke ends `invalid`, `awaitingApproval` or `failed`, so the grid shows the server value. renderer-core adds `revertCellEdit`; renderer-react's `useInvokeAction().invoke` takes an optional `onPhase` callback (design.md decisions 62-64).
+
+- [#66](https://github.com/yosuque/kohaku/pull/66) [`d16f7b3`](https://github.com/yosuque/kohaku/commit/d16f7b367ec62be4875ac18b42fd8be4d9da5c33) Thanks [@yosuque](https://github.com/yosuque)! - `<kohaku-surface>` reads `actionManifest`, `confirm` and `requestApproval` live at invoke time instead of rebuilding the mounted tree when one is reassigned. Assigning a spec and its manifest back to back no longer tears down an L2 sandbox iframe twice, and an inline `confirm` arrow no longer causes a rebuild on every assignment.
+- Updated dependencies [[`a80f17a`](https://github.com/yosuque/kohaku/commit/a80f17a8ac304def877d23df9e7b8e37ef5c7396), [`e250463`](https://github.com/yosuque/kohaku/commit/e2504639145c3baacd1843c72512e8abf4f21b08), [`cb6e91a`](https://github.com/yosuque/kohaku/commit/cb6e91afdbbc083587cd32941ebac07b0151753a), [`171103f`](https://github.com/yosuque/kohaku/commit/171103f58ab87ff98daad8cb12901d417079d76b), [`b712fef`](https://github.com/yosuque/kohaku/commit/b712fef7404c6af1ca6ff726890eb6ddfd44dbfc), [`003e360`](https://github.com/yosuque/kohaku/commit/003e3605159973f6837fccf87f83691b40839483), [`5bb982e`](https://github.com/yosuque/kohaku/commit/5bb982e2fca7d4c609d5b99b6dc71bac95dbfe55), [`f34568b`](https://github.com/yosuque/kohaku/commit/f34568bb40e3c136bfc74e9c7d10c50c812f7e18), [`06a724e`](https://github.com/yosuque/kohaku/commit/06a724e046a432e8c64af217911bb2683ab8ca9d), [`71e17f9`](https://github.com/yosuque/kohaku/commit/71e17f9d970e01abaa8ebdf967054ad468555b56), [`ab25ddc`](https://github.com/yosuque/kohaku/commit/ab25ddc5691e216e6d5d027920a0a9abbc8f4207), [`206b95b`](https://github.com/yosuque/kohaku/commit/206b95b425800ec5af8f7e9ac203a8be70fd8d0b), [`343ccd7`](https://github.com/yosuque/kohaku/commit/343ccd7a71d4370473640dce94f1e2e2a821b39d), [`7c92cc4`](https://github.com/yosuque/kohaku/commit/7c92cc433e40a88f3b43eaeba7fd0af1a8755cad), [`a936266`](https://github.com/yosuque/kohaku/commit/a9362668b281564bc09a3b4a20233f8e1294bf41), [`0a2a43b`](https://github.com/yosuque/kohaku/commit/0a2a43b5ea0cbe90df1bbe53af9137452654e477), [`f8ecb4c`](https://github.com/yosuque/kohaku/commit/f8ecb4c71ba780378849c27c8ccdc6a14b31dcdc), [`4072ca8`](https://github.com/yosuque/kohaku/commit/4072ca8c86f28c2bb79abbfc0483b2e6242b7768)]:
+  - @kohaku-ui/registry@0.4.1
+  - @kohaku-ui/spec-core@0.4.1
+  - @kohaku-ui/data-binding@0.4.1
+  - @kohaku-ui/renderer-core@0.4.1
+  - @kohaku-ui/sandbox@0.4.1
+
+## 0.4.0
+
+### Minor Changes
+
+- [#60](https://github.com/yosuque/kohaku/pull/60) [`5f1bbbd`](https://github.com/yosuque/kohaku/commit/5f1bbbd09fe1edb984a7b0f5a0c5212c3da628ea) Thanks [@yosuque](https://github.com/yosuque)! - Adds a Compliance Evidence Pack export (`@kohaku-ui/lineage`'s new `evidence` module; `kohaku evidence
+  keygen`/`export`/`verify`) and opt-in AI-generation disclosure for both renderers (design.md [#66](https://github.com/yosuque/kohaku/issues/66)/[#67](https://github.com/yosuque/kohaku/issues/67)).
+  
+  **Evidence Pack** (`@kohaku-ui/lineage`): `buildEvidencePack` assembles a normalized, Ed25519-signed
+  export of the lineage log (`events.jsonl`), a governance-decision index (`approvals.jsonl`:
+  `component.reviewed`/`published`/`withdrawn`, `intent.fixated`/`unfixated`), promotion/fixation
+  snapshots, and the referenced component HTML artifacts, plus `manifest.json` and a detached signature
+  (`manifest.sig`). `EvidenceManifestSchema` is new but deliberately not part of `spec/schemas` — it
+  describes an export format for auditors, not a wire type. Ed25519 signing uses `globalThis.crypto.subtle`
+  (no new runtime dependency for TS); an artifact whose recorded hash does not match its own content is
+  still exported, recorded as a non-fatal warning rather than aborting the export.
+  
+  **CLI** (`@kohaku-ui/cli`): `kohaku evidence keygen --out-dir <dir>` generates an Ed25519 keypair (private
+  key file mode 0600). `kohaku evidence export (--data-dir <dir> | --rest <baseUrl> [--header k:v])
+  [--tenant <id>] --since --until --private-key <pem> --out <dir> [--allow-incomplete]` builds and signs a
+  pack from a local `StoragePort` data directory or, over REST, from the existing `KohakuClient` surface
+  (`lineagePages`/`promotions.list`/`fixations.list`) — the REST source leaves `fixations.jsonl` empty with
+  a recorded warning, since `GET /fixations` does not expose enough fields to reconstruct a full
+  `FixationRecord`. `kohaku evidence verify <dir> --public-key <pem>` checks the manifest schema, the
+  signature, and every file's hash/size, and reports an independent artifact-hash cross-check as non-fatal
+  `mismatches`; exit code 0 valid / 1 invalid / 2 usage error. `@kohaku-ui/lineage` and
+  `@kohaku-ui/storage-memory` move from `cli`'s devDependencies to dependencies.
+  
+  **AI-generation disclosure** (`@kohaku-ui/renderer-core`, `@kohaku-ui/renderer-react`,
+  `@kohaku-ui/renderer-wc`): `deriveDisclosure(provenance)` (renderer-core) derives a disclosure level
+  (`"ai-generated"` for tier L1/L2, `"ai-assisted-reviewed"` for a fixated tier-L0 Spec, `"none"` otherwise
+  — never encoded on the wire) and the corresponding `data-kohaku-disclosure`/`data-kohaku-tier`/
+  `data-digital-source-type` (IPTC Digital Source Type) attributes. `SpecView` gains a `disclosure?: "off" |
+  "attributes" | "label"` prop (renderer-react; also exports `useDisclosure`/`KohakuDisclosureLabel`), and
+  `<kohaku-surface>` gains a matching `disclosure` attribute (renderer-wc, applied to the host element,
+  with the visible label — `"label"` mode only — inside the shadow root). Both default to `"off"`: existing
+  DOM output is unchanged unless a host opts in.
+  
+  See [docs/user-guide.md](../docs/user-guide.md)'s "Compliance Evidence Pack and AI-generation disclosure"
+  section for usage, EU AI Act Article 50 context (not legal advice), and a PII caution for exported Intent
+  `params`/request text.
+
+- [#62](https://github.com/yosuque/kohaku/pull/62) [`cc17b7b`](https://github.com/yosuque/kohaku/commit/cc17b7bc3c96e49b1b74197ac20cd7a3d8ee0b47) Thanks [@yosuque](https://github.com/yosuque)! - Add Governed Actions: Human-In-The-Loop tiers for `DomainPort` write operations (design.md [#62](https://github.com/yosuque/kohaku/issues/62)/[#63](https://github.com/yosuque/kohaku/issues/63)/[#64](https://github.com/yosuque/kohaku/issues/64);
+  SPEC §5's ACT-PRM-001/ACT-APR-001/ACT-CNF-001, LIN-ACT-001, §6.2's MCPAPP-ACT-001).
+  
+  An operation may declare `tier` (`"auto"` (default) / `"confirm"` / `"approve"`) and `paramsSchema`
+  (kohaku's own closed JSON Schema subset — `type`, `properties`, `required`,
+  `additionalProperties: false`, `enum`, `minimum`/`maximum`, `minLength`/`maxLength`, `items`, `maxItems`,
+  `x-message`; deliberately no `pattern`, to avoid both ReDoS and a JS/Python regex-dialect mismatch).
+  `spec-core`'s `validateActionParams`/`assertValidActionParamsSchema` (env-neutral, dependency-free, pinned
+  byte-for-byte against the Python port via the cross-language golden) enforces the schema before
+  `DomainPort.invoke` ever runs, on every write surface alike: REST's `POST /binding/action`, MCP's
+  `${prefix}_action`, and the client-side `preflightAction` check `renderer-core` runs before either.
+  
+  `"approve"`-tier actions are gated by a new stateless, short-lived HMAC-signed `ApprovalPort`
+  (`@kohaku-ui/authz-hmac`'s `createHmacApprovalPort`, `"kohaku-approval.v1."`-prefixed tokens, 300s default
+  TTL) bound to `(action, payloadHash, requesterId, tenant)`; self-approval is refused at issuance, and a
+  verification failure the host cannot classify is treated as a denial (fail-closed). An optional
+  `ApprovalStore` adds single-use enforcement. REST gains `POST /approvals` (mints a token as an authorized
+  approver, governance kind `action.approve`) and both the REST body and the MCP action tool's input gain
+  optional `confirmed`/`approval` fields; a gate failure is `422 ACTION_PARAMS_INVALID` / `403
+  APPROVAL_REQUIRED` on REST (with `error.issues`/`error.approval`) and the MCP structured-tool-error
+  equivalent.
+  
+  A compose response optionally carries an **Action manifest** (REST's `actions?` on
+  `/compose`/`/events`/`event: spec`; MCP's `_meta["kohaku/actions"]`) mapping each governed action name to
+  `{tier, paramsSchema?, confirmMessage?}` — placed outside the `UISpec` itself, next to the capability, so
+  it never affects `specHash` or the cache key. `renderer-core`'s `preflightAction` consults it client-side
+  before a write round-trip; `renderer-react`/`renderer-wc`/`mcp-renderer` thread `confirm`/`requestApproval`
+  hooks through (`renderer-react` ships a `globalThis.confirm`-backed default for the `"confirm"` tier; there
+  is no framework-neutral default for `"approve"`, so that tier stays gated until a product wires its own
+  hook). `@kohaku-ui/client`/`@kohaku-ui/data-binding` gain typed `ACTION_PARAMS_INVALID`/`APPROVAL_REQUIRED`
+  error codes and `confirmed`/`approval` request options. A host that records action outcomes to lineage does
+  so under a distinct `action.*` event family (`action.invoked`/`action.denied`/`action.approvalRequested`/
+  `action.approved`), carrying `payloadHash` but never the payload's own field values.
+  
+  The Python port (`python/kohaku`) mirrors the full surface (`kohaku.spec.action_params`,
+  `kohaku.host_core.action_gate`/`action_audit`, `POST /approvals`, the MCP action-tool gate), and
+  `apps/sample-api` / `python/examples/sales-api` demonstrate both tiers end to end (`annotate`: confirm,
+  `publish`: approve) — see the [user guide](../docs/user-guide.md)'s "Governed actions: tiers" section.
+  
+  **Behavior changes to check when upgrading.** (1) `POST /binding/action` and the MCP action tool now
+  reject, before `DomainPort.invoke` runs, any action that is not in the DomainPort's own
+  `listOperations()` — previously such an action was invoked ungated. It is rejected with the same response
+  as a missing write scope and recorded as `action.denied`. A product whose `listOperations()` omits an
+  operation it still expects to be invoked must declare it. (2) `validateActionParams` rejects a payload
+  property named `__proto__`, `constructor` or `prototype` at any depth (issue code `unsafeKey`), whatever
+  the schema's `additionalProperties` says.
+
+- [#54](https://github.com/yosuque/kohaku/pull/54) [`bd2d484`](https://github.com/yosuque/kohaku/commit/bd2d484826bec86c78dcb720502740494a672ea8) Thanks [@yosuque](https://github.com/yosuque)! - Adds a typed way to register a product-specific part, so its `{type, version, propsSchema}` can live in one
+  `ComponentDefinition` instead of being re-typed as string literals at the registration call site (design.md
+  [#68](https://github.com/yosuque/kohaku/issues/68)).
+  
+  `@kohaku-ui/renderer-react`: `implement(def, Component)` wraps a component whose props are inferred from
+  `def.propsSchema` (`z.infer`) — no `node.props["x"] as T` cast needed — and returns an entry consumed by the
+  new `ImplRegistry.use(entry)`. The existing `register(type, version, component)` / `ImplProps` keep working
+  unchanged for parts that have no static `ComponentDefinition` (e.g. a promoted part's per-artifact schema).
+  
+  `@kohaku-ui/renderer-wc`: `<kohaku-surface>` gains a public `registerPart(type, version, builder)` (it was
+  previously private with no way for a host to register anything beyond the core catalog), plus `getPartVersion`
+  for introspection, and `implementWc(def, builder)` is the typed counterpart of `implement` for a `PartBuilder`.
+  
+  Both `implement` and `implementWc` parse a node's props against the schema **unconditionally, in every
+  environment** (`propsSchema.safeParse` is also what materializes a `.default()`-ed prop the Spec omits, not
+  just a validation nicety, so it never skips in production) — on success the component receives the parsed
+  value, on failure it receives the raw (unvalidated) props instead (fail-open: a malformed prop degrades the
+  part's own display rather than the whole surface). Only the diagnostic — a `console.warn` on a mismatch — is
+  gated by environment: by default it fires outside a `NODE_ENV=production` build; pass `{ validate }` to force
+  the warning on or off regardless of environment.
+
+### Patch Changes
+
+- Updated dependencies [[`fcd4eb7`](https://github.com/yosuque/kohaku/commit/fcd4eb7c8c6608030d4f9045648a305fa2e5992f), [`5f1bbbd`](https://github.com/yosuque/kohaku/commit/5f1bbbd09fe1edb984a7b0f5a0c5212c3da628ea), [`cc17b7b`](https://github.com/yosuque/kohaku/commit/cc17b7bc3c96e49b1b74197ac20cd7a3d8ee0b47), [`730e625`](https://github.com/yosuque/kohaku/commit/730e62584b249056078792f6f646019cb225b049), [`730e625`](https://github.com/yosuque/kohaku/commit/730e62584b249056078792f6f646019cb225b049), [`730e625`](https://github.com/yosuque/kohaku/commit/730e62584b249056078792f6f646019cb225b049), [`5d167cb`](https://github.com/yosuque/kohaku/commit/5d167cb386cc1f91102644f8a99bd5b5c2949ce0)]:
+  - @kohaku-ui/registry@0.4.0
+  - @kohaku-ui/renderer-core@0.4.0
+  - @kohaku-ui/spec-core@0.4.0
+  - @kohaku-ui/data-binding@0.4.0
+  - @kohaku-ui/sandbox@0.4.0
+
 ## 0.3.0
 
 ### Patch Changes

package/dist/implement.d.ts

@@ -0,0 +1,37 @@
+import type { ComponentDefinition } from "@kohaku-ui/registry";
+import type { ComponentNode, JsonObject } from "@kohaku-ui/spec-core";
+import type { z } from "zod";
+import type { PartBuilder, RenderRuntime, Teardown } from "./types.js";
+/**
+ * A part builder with typed props, taken from a `ComponentDefinition`'s `propsSchema` (design.md #68).
+ * Same shape as `PartBuilder`, with `props` added between `node` and `row`, so a product's builder never
+ * has to read `node.props["x"] as T` itself — the WC counterpart of renderer-react's typed `Component`.
+ */
+export type TypedPartBuilder<P> = (rt: RenderRuntime, parent: ParentNode, node: ComponentNode, props: P, row: JsonObject | null) => Teardown;
+/** Registration triple returned by `implementWc`, passed to `<kohaku-surface>.registerPart`. */
+export interface PartEntry {
+    type: string;
+    version: string;
+    builder: PartBuilder;
+}
+/**
+ * Wraps a typed `TypedPartBuilder` into a plain `PartBuilder` bound to `def`'s own type and version — the
+ * WC counterpart of renderer-react's `implement` (design.md #68). Usage:
+ * ```ts
+ * const entry = implementWc(myPartDef, (rt, parent, node, props, row) => { ... });
+ * surface.registerPart(entry.type, entry.version, entry.builder);
+ * ```
+ *
+ * `def.propsSchema.safeParse` always runs, in every environment — not just outside a `NODE_ENV=production`
+ * build — because it is also what materializes a `.default()`-ed prop (or any other Zod transform) the Spec
+ * omits; skipping it in production would silently make `builder` see `undefined` for a prop its type says
+ * is always present. On success, `builder` receives `parsed.data`; on failure it receives the raw
+ * (unvalidated) `node.props` instead, matching the renderer's general fail-open policy. The parse (and so
+ * the warning) runs once per `node.props` object rather than on every rebuild. Only the **diagnostic** — a `console.warn` on a mismatch — is gated by environment: by default it fires outside a
+ * `NODE_ENV=production` build (see `isDevEnvironment`); pass `{ validate }` to force it on or off
+ * regardless of environment.
+ */
+export declare function implementWc<P extends z.ZodObject>(def: ComponentDefinition<P>, builder: TypedPartBuilder<z.infer<P>>, options?: {
+    validate?: boolean;
+}): PartEntry;
+//# sourceMappingURL=implement.d.ts.map

package/dist/implement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"implement.d.ts","sourceRoot":"","sources":["../src/implement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEvE;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAChC,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,CAAC,EACR,GAAG,EAAE,UAAU,GAAG,IAAI,KACnB,QAAQ,CAAC;AAEd,gGAAgG;AAChG,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,EAC/C,GAAG,EAAE,mBAAmB,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EACrC,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/B,SAAS,CAyBX"}

package/dist/implement.js

@@ -0,0 +1,44 @@
+import { isDevEnvironment } from "@kohaku-ui/renderer-core";
+/**
+ * Wraps a typed `TypedPartBuilder` into a plain `PartBuilder` bound to `def`'s own type and version — the
+ * WC counterpart of renderer-react's `implement` (design.md #68). Usage:
+ * ```ts
+ * const entry = implementWc(myPartDef, (rt, parent, node, props, row) => { ... });
+ * surface.registerPart(entry.type, entry.version, entry.builder);
+ * ```
+ *
+ * `def.propsSchema.safeParse` always runs, in every environment — not just outside a `NODE_ENV=production`
+ * build — because it is also what materializes a `.default()`-ed prop (or any other Zod transform) the Spec
+ * omits; skipping it in production would silently make `builder` see `undefined` for a prop its type says
+ * is always present. On success, `builder` receives `parsed.data`; on failure it receives the raw
+ * (unvalidated) `node.props` instead, matching the renderer's general fail-open policy. The parse (and so
+ * the warning) runs once per `node.props` object rather than on every rebuild. Only the **diagnostic** — a `console.warn` on a mismatch — is gated by environment: by default it fires outside a
+ * `NODE_ENV=production` build (see `isDevEnvironment`); pass `{ validate }` to force it on or off
+ * regardless of environment.
+ */
+export function implementWc(def, builder, options) {
+    const shouldWarn = options?.validate ?? isDevEnvironment();
+    // Parse once per props object, not once per rebuild: `node.props` keeps its identity for as long as the
+    // Spec does, so a rebuild (and the mismatch warning) reuses the first result. Keyed weakly, so a replaced
+    // Spec's props are collected with it.
+    const resolved = new WeakMap();
+    const wrapped = (rt, parent, node, row) => {
+        let props = resolved.get(node.props);
+        if (props === undefined) {
+            const parsed = def.propsSchema.safeParse(node.props);
+            if (parsed.success) {
+                props = parsed.data;
+            }
+            else {
+                props = node.props;
+                if (shouldWarn) {
+                    console.warn(`[kohaku] component "${def.type}" (node ${node.id}) received props that don't match its schema: ${parsed.error.message}`);
+                }
+            }
+            resolved.set(node.props, props);
+        }
+        return builder(rt, parent, node, props, row);
+    };
+    return { type: def.type, version: def.version, builder: wrapped };
+}
+//# sourceMappingURL=implement.js.map

package/dist/implement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"implement.js","sourceRoot":"","sources":["../src/implement.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAyB5D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CACzB,GAA2B,EAC3B,OAAqC,EACrC,OAAgC;IAEhC,MAAM,UAAU,GAAG,OAAO,EAAE,QAAQ,IAAI,gBAAgB,EAAE,CAAC;IAC3D,wGAAwG;IACxG,0GAA0G;IAC1G,sCAAsC;IACtC,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAsB,CAAC;IACnD,MAAM,OAAO,GAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QACrD,IAAI,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACnB,KAAK,GAAG,MAAM,CAAC,IAAkB,CAAC;YACpC,CAAC;iBAAM,CAAC;gBACN,KAAK,GAAG,IAAI,CAAC,KAAmB,CAAC;gBACjC,IAAI,UAAU,EAAE,CAAC;oBACf,OAAO,CAAC,IAAI,CACV,uBAAuB,GAAG,CAAC,IAAI,WAAW,IAAI,CAAC,EAAE,iDAAiD,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CACzH,CAAC;gBACJ,CAAC;YACH,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;IAC/C,CAAC,CAAC;IACF,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AACpE,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { DEFAULT_MESSAGES, type RendererMessages } from "@kohaku-ui/renderer-core";
+export { type ActionManifest, type ActionManifestEntry, DEFAULT_MESSAGES, type PreflightActionResult, preflightAction, type RendererMessages, summarizeActionForModel, } from "@kohaku-ui/renderer-core";
+export { implementWc, type PartEntry, type TypedPartBuilder } from "./implement.js";
 export { defineKohakuSurface, KOHAKU_EVENT, KohakuSurface } from "./kohaku-surface.js";
 export { createCoreRenderRegistry } from "./registry.js";
 export type { ActionPhase, PartBuilder, RenderRuntime, SurfaceContext, SurfaceEvent, Teardown, } from "./types.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,YAAY,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,QAAQ,GACT,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,eAAe,EACf,KAAK,gBAAgB,EACrB,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACpF,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,YAAY,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,QAAQ,GACT,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -2,7 +2,10 @@
 // A single <kohaku-surface> builds the entire UI Spec tree into one shadow root. The shared core is renderer-core.
 // Dependency direction: spec-core → {registry, data-binding} → renderer-core → renderer-wc (sandbox is imported directly).
 // UI message type and defaults (the single source of truth is renderer-core). Used to override context.messages.
-export { DEFAULT_MESSAGES } from "@kohaku-ui/renderer-core";
+// Governed actions (design.md #62/#63/#64): re-exported from renderer-core (the framework-free source of
+// truth) so a consumer does not need to reach into @kohaku-ui/renderer-core directly for these.
+export { DEFAULT_MESSAGES, preflightAction, summarizeActionForModel, } from "@kohaku-ui/renderer-core";
+export { implementWc } from "./implement.js";
 export { defineKohakuSurface, KOHAKU_EVENT, KohakuSurface } from "./kohaku-surface.js";
 export { createCoreRenderRegistry } from "./registry.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,mHAAmH;AACnH,2HAA2H;AAE3H,iHAAiH;AACjH,OAAO,EAAE,gBAAgB,EAAyB,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,mHAAmH;AACnH,2HAA2H;AAE3H,iHAAiH;AACjH,yGAAyG;AACzG,gGAAgG;AAChG,OAAO,EAGL,gBAAgB,EAEhB,eAAe,EAEf,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAyC,MAAM,gBAAgB,CAAC;AACpF,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC"}

package/dist/kohaku-surface.d.ts

@@ -1,8 +1,10 @@
 import { type RendererMessages } from "@kohaku-ui/renderer-core";
 import { type ThemeTokens, type UISpec } from "@kohaku-ui/spec-core";
-import type { SurfaceContext } from "./types.js";
+import type { PartBuilder, SurfaceContext } from "./types.js";
 /** Name of the forward event dispatched by <kohaku-surface> (detail is a SurfaceEvent). */
 export declare const KOHAKU_EVENT = "kohaku-event";
+/** `disclosure` attribute values (design.md #66); anything else (including absence) behaves as `"off"`. */
+type DisclosureMode = "off" | "attributes" | "label";
 /**
  * The single host element <kohaku-surface> (Shadow DOM). It builds the entire UI Spec tree into one shadow root
  * (rather than a Custom Element per part type — a single-element surface). Spec / context are received as properties.
@@ -15,8 +17,13 @@ export declare const KOHAKU_EVENT = "kohaku-event";
  */
 export declare class KohakuSurface extends HTMLElement {
     #private;
+    static get observedAttributes(): string[];
     constructor();
     connectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /** `"off"` (default) | `"attributes"` | `"label"` (design.md #66). Reflects the `disclosure` attribute. */
+    get disclosure(): DisclosureMode;
+    set disclosure(v: DisclosureMode);
     disconnectedCallback(): void;
     /** UI Spec. Setting it triggers resetForIntent → rebuild the tree + reattach the controller. */
     get spec(): UISpec | null;
@@ -35,8 +42,38 @@ export declare class KohakuSurface extends HTMLElement {
     set onEvent(v: SurfaceContext["onEvent"]);
     set onNodeError(v: SurfaceContext["onNodeError"]);
     set onActionResult(v: SurfaceContext["onActionResult"]);
+    set actionManifest(v: SurfaceContext["actionManifest"]);
+    set confirm(v: SurfaceContext["confirm"]);
+    set requestApproval(v: SurfaceContext["requestApproval"]);
     set sandbox(v: SurfaceContext["sandbox"]);
+    /**
+     * Public registration API for product-specific parts (design.md #68). Previously `#registry` was private
+     * with no way for a host to add its own component types — a product could not register anything beyond
+     * the core catalog on the WC surface at all. Pair with `implementWc` for typed props:
+     * ```ts
+     * const entry = implementWc(myPartDef, builder);
+     * surface.registerPart(entry.type, entry.version, entry.builder);
+     * ```
+     * `version` is recorded for parity with renderer-react's `ImplRegistry.register`; unlike that registry,
+     * this surface does not (yet) feed a `SurfaceCapabilities` table into `@kohaku-ui/registry`'s
+     * `negotiate()` — no host wires WC capability negotiation today (AGENTS.md's renderer-wc section) — so
+     * `version` is not itself consulted by any negotiation path yet. Call before assigning `spec` when
+     * possible; if a Spec is already mounted, this rebuilds it so the newly registered part renders
+     * immediately instead of only taking effect on the next Spec swap.
+     *
+     * `#registry` starts seeded with the 16 core-catalog parts (`createCoreRenderRegistry`), so registering
+     * an already-taken `type` — most easily a core one, by typo or intentional override — silently replaces
+     * it. That is sometimes exactly what a product wants (replacing a core part with its own), but silent
+     * shadowing of a core part is also an easy way to lose one by accident, so replacing any existing entry
+     * warns via `console.warn` unless the caller opts in explicitly with `{ override: true }`.
+     */
+    registerPart(type: string, version: string, builder: PartBuilder, options?: {
+        override?: boolean;
+    }): void;
+    /** The version last passed to `registerPart` for `type`, if any (introspection only — see its doc comment). */
+    getPartVersion(type: string): string | undefined;
 }
 /** Registers <kohaku-surface> as a custom element (idempotent). */
 export declare function defineKohakuSurface(tagName?: string): void;
+export {};
 //# sourceMappingURL=kohaku-surface.d.ts.map

package/dist/kohaku-surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kohaku-surface.d.ts","sourceRoot":"","sources":["../src/kohaku-surface.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,gBAAgB,EAItB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAqB,KAAK,WAAW,EAAE,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAIxF,OAAO,KAAK,EAAe,cAAc,EAAY,MAAM,YAAY,CAAC;AAExE,2FAA2F;AAC3F,eAAO,MAAM,YAAY,iBAAiB,CAAC;AA0B3C;;;;;;;;;GASG;AACH,qBAAa,aAAc,SAAQ,WAAW;;IAW5C,cAYC;IAED,iBAAiB,IAAI,IAAI,CAUxB;IAED,oBAAoB,IAAI,IAAI,CAG3B;IAUD,gGAAgG;IAChG,IAAI,IAAI,IAAI,MAAM,GAAG,IAAI,CAExB;IACD,IAAI,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAK3B;IAED;;;OAGG;IACH,IAAI,OAAO,IAAI,cAAc,CAE5B;IACD,IAAI,OAAO,CAAC,IAAI,EAAE,cAAc,EAG/B;IAED,4EAA4E;IAC5E,IAAI,OAAO,CAAC,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,EAEvC;IACD,IAAI,KAAK,CAAC,CAAC,EAAE,WAAW,GAAG,SAAS,EAEnC;IACD,IAAI,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAE/B;IACD,IAAI,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,SAAS,EAEpD;IACD,IAAI,OAAO,CAAC,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,EAEvC;IACD,IAAI,WAAW,CAAC,CAAC,EAAE,cAAc,CAAC,aAAa,CAAC,EAE/C;IACD,IAAI,cAAc,CAAC,CAAC,EAAE,cAAc,CAAC,gBAAgB,CAAC,EAErD;IACD,IAAI,OAAO,CAAC,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,EAEvC;CA2EF;AAED,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,OAAO,SAAmB,GAAG,IAAI,CAIpE"}
+{"version":3,"file":"kohaku-surface.d.ts","sourceRoot":"","sources":["../src/kohaku-surface.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,gBAAgB,EAItB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAqB,KAAK,WAAW,EAAE,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAIxF,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAY,MAAM,YAAY,CAAC;AAExE,2FAA2F;AAC3F,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAiC3C,2GAA2G;AAC3G,KAAK,cAAc,GAAG,KAAK,GAAG,YAAY,GAAG,OAAO,CAAC;AAErD;;;;;;;;;GASG;AACH,qBAAa,aAAc,SAAQ,WAAW;;IAqB5C,MAAM,KAAK,kBAAkB,IAAI,MAAM,EAAE,CAExC;IAED,cAYC;IAED,iBAAiB,IAAI,IAAI,CAWxB;IAED,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAE7F;IAED,2GAA2G;IAC3G,IAAI,UAAU,IAAI,cAAc,CAG/B;IACD,IAAI,UAAU,CAAC,CAAC,EAAE,cAAc,EAG/B;IAED,oBAAoB,IAAI,IAAI,CAG3B;IAUD,gGAAgG;IAChG,IAAI,IAAI,IAAI,MAAM,GAAG,IAAI,CAExB;IACD,IAAI,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAK3B;IAED;;;OAGG;IACH,IAAI,OAAO,IAAI,cAAc,CAE5B;IACD,IAAI,OAAO,CAAC,IAAI,EAAE,cAAc,EAG/B;IAED,4EAA4E;IAC5E,IAAI,OAAO,CAAC,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,EAEvC;IACD,IAAI,KAAK,CAAC,CAAC,EAAE,WAAW,GAAG,SAAS,EAEnC;IACD,IAAI,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAE/B;IACD,IAAI,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,SAAS,EAEpD;IACD,IAAI,OAAO,CAAC,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,EAEvC;IACD,IAAI,WAAW,CAAC,CAAC,EAAE,cAAc,CAAC,aAAa,CAAC,EAE/C;IACD,IAAI,cAAc,CAAC,CAAC,EAAE,cAAc,CAAC,gBAAgB,CAAC,EAErD;IACD,IAAI,cAAc,CAAC,CAAC,EAAE,cAAc,CAAC,gBAAgB,CAAC,EAErD;IACD,IAAI,OAAO,CAAC,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,EAEvC;IACD,IAAI,eAAe,CAAC,CAAC,EAAE,cAAc,CAAC,iBAAiB,CAAC,EAEvD;IACD,IAAI,OAAO,CAAC,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,EAEvC;IAoBD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAUxG;IAED,+GAA+G;IAC/G,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE/C;CAuHF;AAED,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,OAAO,SAAmB,GAAG,IAAI,CAIpE"}

package/dist/kohaku-surface.js

@@ -1,4 +1,4 @@
-import { createDataInvalidationBus, createSpecStateStore, DEFAULT_LOCALE, DEFAULT_MESSAGES, PARTS_STATE_CSS, themeTokensToCssVars, } from "@kohaku-ui/renderer-core";
+import { createDataInvalidationBus, createSpecStateStore, DEFAULT_LOCALE, DEFAULT_MESSAGES, deriveDisclosure, disclosureDomAttributes, PARTS_STATE_CSS, themeTokensToCssVars, } from "@kohaku-ui/renderer-core";
 import { ROOT_COMPONENT_ID } from "@kohaku-ui/spec-core";
 import { noop } from "./dom.js";
 import { createCoreRenderRegistry } from "./registry.js";
@@ -9,9 +9,12 @@ export const KOHAKU_EVENT = "kohaku-event";
  * Individual context properties whose change requires tearing down and rebuilding the mounted tree
  * (they are baked into the RenderRuntime at #render time — binding/theme/locale/messages feed the
  * BoundDataController / theme resolution / message lookup, and sandbox is read at mount time by the
- * sandbox.html part builder). `onEvent` / `onNodeError` / `onActionResult` are deliberately **not** in
- * this set: they are read live from `#context` at call time (see `#dispatchForward` and the wrapper
- * closures built in `#render`), so reassigning one of them mid-lifecycle must not force a full rebuild.
+ * sandbox.html part builder). `onEvent` / `onNodeError` / `onActionResult` and the action-governance
+ * hooks `actionManifest` / `confirm` / `requestApproval` are deliberately **not** in this set: they are
+ * read live from `#context` at call time (see `#dispatchForward` and the wrapper closures / getters built
+ * in `#render`), so reassigning one of them mid-lifecycle must not force a full rebuild -- which would
+ * tear down every mounted L2 sandbox iframe, and would fire twice when a host assigns the spec and its
+ * manifest back to back.
  */
 const REBUILD_KEYS = new Set(["binding", "theme", "locale", "messages", "sandbox"]);
 /** Every property <kohaku-surface> exposes as a plain instance accessor (used by #upgradeProperty). */
@@ -25,7 +28,11 @@ const UPGRADE_PROPS = [
     "onEvent",
     "onNodeError",
     "onActionResult",
+    "actionManifest",
+    "confirm",
+    "requestApproval",
     "sandbox",
+    "disclosure",
 ];
 /**
  * The single host element <kohaku-surface> (Shadow DOM). It builds the entire UI Spec tree into one shadow root
@@ -42,10 +49,22 @@ export class KohakuSurface extends HTMLElement {
     #spec = null;
     #context = {};
     #registry = createCoreRenderRegistry();
+    // version is not read by #render (RenderRuntime.registry only needs the builder); it is recorded purely
+    // for parity with renderer-react's ImplRegistry.register (see registerPart's doc comment).
+    #partVersions = new Map();
     // The store is retained by intent.hash; the bus stays the same for the surface's lifetime (equivalent to renderer-react's Provider useRef bus).
     #store = null;
     #bus = createDataInvalidationBus();
     #teardown = noop;
+    // AI-generation disclosure (design.md #66). Unlike the properties above, `disclosure` is attribute-backed
+    // (`static observedAttributes` + `attributeChangedCallback`) rather than a plain instance accessor: it is
+    // a simple serializable enum, well suited to `<kohaku-surface disclosure="label">` markup, unlike
+    // spec/context/binding/theme which need real object identity. #disclosureLabelEl is the shadow-root
+    // element `#applyDisclosure` creates on demand for `disclosure="label"`; null in every other mode.
+    #disclosureLabelEl = null;
+    static get observedAttributes() {
+        return ["disclosure"];
+    }
     constructor() {
         super();
         const shadow = this.attachShadow({ mode: "open" });
@@ -66,12 +85,28 @@ export class KohakuSurface extends HTMLElement {
         // forever, so its setter logic (patchContext / re-render) would never fire again once the element is
         // upgraded. Re-apply each such value through its accessor exactly once, here, at upgrade time
         // (connectedCallback always fires after the class is defined). A no-op for an element created after
-        // define() (no own-property was ever set).
+        // define() (no own-property was ever set). "disclosure" is listed last so, if it was pre-assigned
+        // alongside "spec", #render() (triggered by spec's own upgrade) already sees the right value.
         for (const prop of UPGRADE_PROPS)
             this.#upgradeProperty(prop);
         if (this.#spec != null)
             this.#render();
     }
+    attributeChangedCallback(name, oldValue, newValue) {
+        if (name === "disclosure" && oldValue !== newValue)
+            this.#applyDisclosure();
+    }
+    /** `"off"` (default) | `"attributes"` | `"label"` (design.md #66). Reflects the `disclosure` attribute. */
+    get disclosure() {
+        const v = this.getAttribute("disclosure");
+        return v === "attributes" || v === "label" ? v : "off";
+    }
+    set disclosure(v) {
+        if (v === "off")
+            this.removeAttribute("disclosure");
+        else
+            this.setAttribute("disclosure", v);
+    }
     disconnectedCallback() {
         this.#teardown();
         this.#teardown = noop;
@@ -129,6 +164,15 @@ export class KohakuSurface extends HTMLElement {
     set onActionResult(v) {
         this.#patchContext({ onActionResult: v });
     }
+    set actionManifest(v) {
+        this.#patchContext({ actionManifest: v });
+    }
+    set confirm(v) {
+        this.#patchContext({ confirm: v });
+    }
+    set requestApproval(v) {
+        this.#patchContext({ requestApproval: v });
+    }
     set sandbox(v) {
         this.#patchContext({ sandbox: v });
     }
@@ -152,14 +196,51 @@ export class KohakuSurface extends HTMLElement {
         if (needsRebuild && this.#spec != null)
             this.#render();
     }
+    /**
+     * Public registration API for product-specific parts (design.md #68). Previously `#registry` was private
+     * with no way for a host to add its own component types — a product could not register anything beyond
+     * the core catalog on the WC surface at all. Pair with `implementWc` for typed props:
+     * ```ts
+     * const entry = implementWc(myPartDef, builder);
+     * surface.registerPart(entry.type, entry.version, entry.builder);
+     * ```
+     * `version` is recorded for parity with renderer-react's `ImplRegistry.register`; unlike that registry,
+     * this surface does not (yet) feed a `SurfaceCapabilities` table into `@kohaku-ui/registry`'s
+     * `negotiate()` — no host wires WC capability negotiation today (AGENTS.md's renderer-wc section) — so
+     * `version` is not itself consulted by any negotiation path yet. Call before assigning `spec` when
+     * possible; if a Spec is already mounted, this rebuilds it so the newly registered part renders
+     * immediately instead of only taking effect on the next Spec swap.
+     *
+     * `#registry` starts seeded with the 16 core-catalog parts (`createCoreRenderRegistry`), so registering
+     * an already-taken `type` — most easily a core one, by typo or intentional override — silently replaces
+     * it. That is sometimes exactly what a product wants (replacing a core part with its own), but silent
+     * shadowing of a core part is also an easy way to lose one by accident, so replacing any existing entry
+     * warns via `console.warn` unless the caller opts in explicitly with `{ override: true }`.
+     */
+    registerPart(type, version, builder, options) {
+        if (this.#registry.has(type) && options?.override !== true) {
+            console.warn(`[kohaku] registerPart("${type}", ...) replaces an existing part. ` +
+                "Pass { override: true } if that is intentional.");
+        }
+        this.#registry.set(type, builder);
+        this.#partVersions.set(type, version);
+        if (this.#spec != null)
+            this.#render();
+    }
+    /** The version last passed to `registerPart` for `type`, if any (introspection only — see its doc comment). */
+    getPartVersion(type) {
+        return this.#partVersions.get(type);
+    }
     #render() {
         // Tear down the previous tree (controller detach / unsubscribe / sandbox destroy / anchor removal).
         this.#teardown();
         this.#teardown = noop;
         this.#root.replaceChildren();
         const spec = this.#spec;
-        if (spec == null)
+        if (spec == null) {
+            this.#applyDisclosure();
             return;
+        }
         const theme = this.#context.theme ?? {};
         const messages = { ...DEFAULT_MESSAGES, ...(this.#context.messages ?? {}) };
         const locale = this.#context.locale ?? DEFAULT_LOCALE;
@@ -175,6 +256,7 @@ export class KohakuSurface extends HTMLElement {
         for (const [name, value] of Object.entries(themeTokensToCssVars(theme))) {
             this.style.setProperty(name, value);
         }
+        const liveContext = () => this.#context;
         const rt = createRuntime({
             spec,
             store: this.#store,
@@ -187,21 +269,77 @@ export class KohakuSurface extends HTMLElement {
             // just one of these callbacks does not go through #render again, so RenderRuntime's own onNodeError/
             // onActionResult fields (baked in once here) must forward through a stable indirection instead of
             // holding a stale reference to whatever callback existed when the tree was last built.
+            // actionManifest / confirm / requestApproval are exposed as getters for the same reason: they are
+            // consulted per invoke, so a reassignment takes effect on the next action without a rebuild.
             ctx: {
                 ...this.#context,
                 onNodeError: (args) => this.#context.onNodeError?.(args),
                 onActionResult: (args) => this.#context.onActionResult?.(args),
+                get actionManifest() {
+                    return liveContext().actionManifest;
+                },
+                get confirm() {
+                    return liveContext().confirm;
+                },
+                get requestApproval() {
+                    return liveContext().requestApproval;
+                },
             },
             registry: this.#registry,
             dispatchForward: (event) => this.#dispatchForward(event),
         });
         this.#teardown = mountTree(rt, this.#root, ROOT_COMPONENT_ID);
+        this.#applyDisclosure();
     }
     #dispatchForward(event) {
         // composed so it crosses the shadow boundary and reaches the host page. Flows to both paths regardless of whether a sink exists.
         this.dispatchEvent(new CustomEvent(KOHAKU_EVENT, { detail: event, bubbles: true, composed: true }));
         this.#context.onEvent?.(event);
     }
+    /**
+     * Applies (or clears) AI-generation disclosure (design.md #66): the `data-kohaku-disclosure` /
+     * `data-kohaku-tier` / `data-digital-source-type` attributes go on the *host* element itself (`this`),
+     * not inside the shadow root -- unlike renderer-react's SpecView, which has no host element of its own
+     * to mark and so wraps the tree in an internal `<div>` instead. The visible label (`disclosure="label"`
+     * only) is a shadow-root element, since that is what is actually displayed. Called from `#render()`
+     * (spec/context changes) and from `attributeChangedCallback` (the `disclosure` attribute changing on
+     * its own, with no other change to re-render for).
+     */
+    #applyDisclosure() {
+        const mode = this.disclosure;
+        if (mode === "off" || this.#spec == null) {
+            this.removeAttribute("data-kohaku-disclosure");
+            this.removeAttribute("data-kohaku-tier");
+            this.removeAttribute("data-digital-source-type");
+            this.#disclosureLabelEl?.remove();
+            this.#disclosureLabelEl = null;
+            return;
+        }
+        const disclosure = deriveDisclosure(this.#spec.provenance);
+        const attrs = disclosureDomAttributes(disclosure);
+        this.setAttribute("data-kohaku-disclosure", attrs["data-kohaku-disclosure"]);
+        this.setAttribute("data-kohaku-tier", attrs["data-kohaku-tier"]);
+        if (attrs["data-digital-source-type"] != null) {
+            this.setAttribute("data-digital-source-type", attrs["data-digital-source-type"]);
+        }
+        else {
+            this.removeAttribute("data-digital-source-type");
+        }
+        if (mode === "label" && disclosure.level !== "none") {
+            const messages = { ...DEFAULT_MESSAGES, ...(this.#context.messages ?? {}) };
+            const text = disclosure.level === "ai-generated" ? messages.disclosureAiGenerated : messages.disclosureAiReviewed;
+            if (this.#disclosureLabelEl == null) {
+                this.#disclosureLabelEl = document.createElement("div");
+                this.#disclosureLabelEl.setAttribute("data-kohaku-disclosure-label", "");
+                this.shadowRoot.insertBefore(this.#disclosureLabelEl, this.#root);
+            }
+            this.#disclosureLabelEl.textContent = text;
+        }
+        else {
+            this.#disclosureLabelEl?.remove();
+            this.#disclosureLabelEl = null;
+        }
+    }
 }
 /** Registers <kohaku-surface> as a custom element (idempotent). */
 export function defineKohakuSurface(tagName = "kohaku-surface") {