Widget: canonical design discussion

[DevilTea]

Widget canonical design discussion

This Discussion is the canonical continuation point for long-lived Widget architecture across @deviltea/widget-core, @deviltea/widget-vue, Widget Lab, inspection/devtools, and deferred MCP integration.

The project moved from DevilTea/deviltea-labs to DevilTea/widget. This Discussion intentionally brings the design authority with it instead of leaving current architecture dependent on open canonical issues in the former repository.

Authority and workflow

1. Shipped behavior and source in DevilTea/widget are the current implementation baseline.
2. The migrated historical topics below preserve the complete bodies/comments of deviltea-labs #10, #13, #54, and #55. Later explicit accepted decisions within those histories retain their original precedence for their stated scope unless superseded here.
3. New long-lived architecture discussion continues here by topic/reply.
4. Concrete implementation, bug, spike, or bounded design work remains in DevilTea/widget Issues and links back here when it changes a durable invariant.
5. Do not reopen Widget architecture work in deviltea-labs; that repository is historical for Widget.

Current live work

• DevilTea/widget#3 — descendant-scoped dependency/provider semantics.
• DevilTea/widget#5 — Preview isolation and extension-ready inspector transport.

These remain Issues because they still represent bounded active work. Accepted durable outcomes should be folded into the relevant topic here.

[DevilTea]

Core composition architecture

Historical high-level Core authority.

Historical source: DevilTea/deviltea-labs#10 — Widget composition core architecture — canonical decision log.

The replies below preserve the source issue body and chronological comments as migration history.

[DevilTea]

Migrated comment 145 from DevilTea/deviltea-labs#10 — @DevilTea, 2026-09-01T15:10:52Z
Original: DevilTea/deviltea-labs#10 (comment)

CURRENT / ACCEPTED — WidgetSystem.catalog is a narrow immutable descriptive projection

Cross-cutting Core authoring-projection invariant mirrored from #54.

Accepted:

• system.catalog is an immutable projection over the Plugins registered in that WidgetSystem, not a second registry/domain object;
• public shape is conceptually WidgetCatalog { readonly widgets: readonly WidgetCatalogEntry[] };
• each entry exposes only Plugin type, required Plugin description, and the existing intrinsic config/slot description projection;
• Catalog does not expose Plugin objects, implementation callbacks, Runtime state/property/method definitions, or a duplicated capability model;
• config/slot presence remains represented by existing intrinsic-description null versus non-null semantics;
• no independent Catalog entry identity is introduced beyond Plugin type;
• WidgetSystem remains the sole Plugin registry and semantic authority; Catalog owns no independent lifecycle or validity rules.

Canonical invariant:

WidgetSystem.catalog is a narrow immutable authoring projection of intrinsic Plugin descriptions. It supports authoring/tooling without becoming a second Plugin registry or generic Runtime/Plugin inspection API.

[DevilTea]

Migrated comment 146 from DevilTea/deviltea-labs#10 — @DevilTea, 2026-09-01T15:33:04Z
Original: DevilTea/deviltea-labs#10 (comment)

CURRENT / ACCEPTED — WidgetCatalog preserves Plugin registration order

Cross-cutting Core projection rule mirrored from #54:

• WidgetCatalog.widgets preserves the owning WidgetSystem's registered Plugin tuple / registration order.
• The order is deterministic enumeration only.
• It carries no semantic priority, matching precedence, rendering priority, validation precedence, or Runtime behavior.

Canonical invariant:

Catalog enumeration follows WidgetSystem Plugin registration order and has no semantic priority.

[DevilTea]

Migrated comment 147 from DevilTea/deviltea-labs#10 — @DevilTea, 2026-09-01T15:35:44Z
Original: DevilTea/deviltea-labs#10 (comment)

CURRENT / ACCEPTED — ApplyPatchFailure is the sole public umbrella for expected Document patch failures

Cross-cutting Core naming consolidation mirrored from #54.

type ApplyPatchResult = Result<
  { readonly changed: boolean },
  ApplyPatchFailure
>

type ApplyPatchFailure =
  | SourcePatchOperationFailure
  | ReentrantApplyFailure
  | DocumentRevisionConflictFailure

• ApplyPatchFailure is the sole public umbrella for all expected WidgetDocument.applyPatch() failures.
• SourcePatchOperationFailure is only for failures attributable to a specific SourcePatch operation and carries operationIndex.
• ReentrantApplyFailure and DocumentRevisionConflictFailure are Document-level lifecycle/concurrency failures, not SourcePatch-operation failures.
• Earlier umbrella naming SourcePatchFailure is superseded and is not retained as a public alias.
• The accepted SourcePatchOperationFailureCode taxonomy remains scoped to SourcePatchOperationFailure.

Canonical invariant:

ApplyPatchFailure is the sole public umbrella for expected WidgetDocument.applyPatch() failures. SourcePatchOperationFailure represents only failures attributable to a specific SourcePatch operation and therefore carries operationIndex; Document lifecycle/concurrency failures remain sibling branches rather than being mislabeled as SourcePatch failures.

[DevilTea]

Migrated comment 148 from DevilTea/deviltea-labs#10 — @DevilTea, 2026-09-01T15:43:02Z
Original: DevilTea/deviltea-labs#10 (comment)

CURRENT / ACCEPTED — non-MCP Core redesign architecture freeze

The #10 body has been reconsolidated on 2026-09-01 to match the accepted detailed contract in #54.

The non-MCP Core / authored-document redesign is now implementation-ready.

Canonical split:

• feat(widget-lab): host Preview Runtime and renderer inside iframe #10 — high-level living Core architecture;
• #54 — detailed authored-source / Blueprint / WidgetDocument / SourcePatch / Catalog specification;
• #55 — Widget MCP integration, deferred/paused;
• feat(devtools): build Chromium DevTools extension spike and runtime discovery hook #13 — Lab / Vue renderer-specific architecture when applicable.

Do not delay the current redesign for speculative persistence, transport, MCP, editor UX, or future compatibility design. Add an architecture amendment only when implementation exposes a real contradiction, a public semantic must change, or a downstream package proves a missing Core contract.

Future intentional contract changes must be marked explicitly CURRENT / ACCEPTED; later accepted amendments supersede this consolidated body only for their stated scope until the next reconsolidation.

[DevilTea]

Migrated comment 149 from DevilTea/deviltea-labs#10 — @DevilTea, 2026-09-02T03:37:18Z
Original: DevilTea/deviltea-labs#10 (comment)

CURRENT / ACCEPTED — exact-source JSON proof retains precise Diagnostic causes

Cross-cutting Core amendment mirrored from #54 after implementation review of #56 exposed a concrete freeze gap.

For the exact Blueprint.source JSON-domain proof:

• confirmed authored-domain violations use Blueprint Diagnostic code json-incompatible-value;
• that variant carries a source-rooted required path and the closed framework-owned JsonCompatibilityReason union:

undefined
non-finite-number
bigint
symbol
function
unsupported-object-prototype
symbol-key
accessor-property
sparse-array
array-extra-property
cyclic-reference

• unsupported-object-prototype is intentionally semantic/general rather than a Date / Map / Set / class-instance taxonomy;
• accessor-backed authored properties are detected by descriptor and never invoked;
• cyclic-reference means active-path recursion, not repeated acyclic aliasing;
• inability to safely complete source reflection/inspection is not JSON incompatibility and uses a distinct Blueprint Diagnostic code source-access-failed with a source-rooted required path and no reflection-mechanics reason;
• the source-access-failed string is deliberately compatible with the existing SourcePatch Failure vocabulary while remaining a different discriminated protocol/payload;
• whole-source inspection aggregates independent safe findings deterministically and locally stops at unsafe fragments;
• public sourceJsonCompatible remains fail-closed boolean proof: false covers confirmed incompatibility or unproven inspection, while Diagnostics retain the distinction;
• existing sourceJsonCompatible:false → status:'invalid' semantics remain unchanged.

Canonical invariant:

Blueprint exact-source JSON proof is fail-closed, but its Diagnostics distinguish confirmed domain violation (json-incompatible-value + closed semantic reason) from inability to safely inspect (source-access-failed). Public machine taxonomy describes authored/recovery semantics rather than reflection implementation details.

[DevilTea]

Authored source, Blueprint, WidgetDocument, and SourcePatch

Historical detailed Core authored-document authority.

Historical source: DevilTea/deviltea-labs#54 — design: authorable widget documents, metadata, and source mutation.

The replies below preserve the source issue body and chronological comments as migration history.

[DevilTea]

Migrated comment 106 from DevilTea/deviltea-labs#54 — @DevilTea, 2026-09-01T15:10:41Z
Original: DevilTea/deviltea-labs#54 (comment)

CURRENT / ACCEPTED — WidgetSystem.catalog is a narrow immutable descriptive projection

Accepted authoring-projection contract:

interface WidgetCatalog {
  readonly widgets: readonly WidgetCatalogEntry[]
}

interface WidgetCatalogEntry {
  readonly type: string
  readonly description: string

  readonly descriptions: {
    readonly config: string | null
    readonly slots: ReadonlyMap<WidgetMemberKey, string> | null
  }
}

Rules:

• system.catalog is an immutable projection over the Plugins registered in that WidgetSystem; it is not a second registry/domain object.
• each entry exposes only the Plugin type, required Plugin description, and the already-authoritative intrinsic config/slot description projection;
• Catalog does not expose Plugin objects, semantic implementation callbacks, Runtime state/property/method definitions, or a duplicated capabilities object;
• config/slot declaration presence continues to use the existing intrinsic-description semantics:
  • descriptions.config === null iff config capability is absent;
  • descriptions.slots === null iff slots capability is absent;
  • an explicitly declared empty slots capability yields a non-null empty readonly map;
• no independent Catalog entry ID/key is added; Plugin type is the semantic Widget-type identity;
• WidgetSystem remains the sole Plugin registry and semantic authority; Catalog owns no independent registration, refresh, validity, or mutation lifecycle.

The wrapper WidgetCatalog { widgets } is retained as a stable authoring-projection namespace rather than exposing the Catalog itself as a bare array. Future derived authoring views may only be added when justified; this decision does not pre-authorize a generic Plugin-inspection API.

Canonical invariant:

WidgetSystem.catalog is a narrow immutable authoring projection of intrinsic Plugin descriptions. It describes which Widget types exist and the authored config/slot semantics available to consumers without exposing or duplicating the Plugin implementation/runtime model.

[DevilTea]

Migrated comment 107 from DevilTea/deviltea-labs#54 — @DevilTea, 2026-09-01T15:32:56Z
Original: DevilTea/deviltea-labs#54 (comment)

CURRENT / ACCEPTED — WidgetCatalog preserves Plugin registration order

Accepted deterministic enumeration rule for the Core authoring projection:

• WidgetCatalog.widgets preserves the owning WidgetSystem's registered Plugin tuple / registration order.
• The order exists only as deterministic projection/enumeration order for authoring consumers, docs, tests, and tooling.
• Catalog order does not imply Widget semantic priority, matching precedence, rendering priority, validation precedence, or Runtime behavior.
• Core does not sort Catalog entries by Plugin type, description, or another derived key.

Canonical invariant:

WidgetCatalog.widgets preserves WidgetSystem Plugin registration order as deterministic enumeration only; that order carries no semantic priority.

[DevilTea]

Migrated comment 108 from DevilTea/deviltea-labs#54 — @DevilTea, 2026-09-01T15:35:34Z
Original: DevilTea/deviltea-labs#54 (comment)

CURRENT / ACCEPTED — ApplyPatchFailure is the sole public umbrella for expected Document patch failures

Accepted naming consolidation for WidgetDocument.applyPatch(...) expected failures.

type ApplyPatchResult = Result<
  { readonly changed: boolean },
  ApplyPatchFailure
>

type ApplyPatchFailure =
  | SourcePatchOperationFailure
  | ReentrantApplyFailure
  | DocumentRevisionConflictFailure

Rules:

• ApplyPatchFailure is the sole public umbrella for all expected WidgetDocument.applyPatch() failures.
• SourcePatchOperationFailure is reserved for a failure attributable to one concrete SourcePatch operation and therefore carries operationIndex.
• ReentrantApplyFailure is a Document lifecycle failure, not a SourcePatch-operation failure.
• DocumentRevisionConflictFailure is a Document optimistic-concurrency failure and is detected before SourcePatch operation evaluation.
• Earlier umbrella naming SourcePatchFailure is superseded and is not retained as a public alias.
• The previously accepted SourcePatchOperationFailureCode taxonomy remains scoped only to SourcePatchOperationFailure.

Canonical invariant:

ApplyPatchFailure is the sole public umbrella for expected WidgetDocument.applyPatch() failures. SourcePatchOperationFailure represents only failures attributable to a specific SourcePatch operation and therefore carries operationIndex. Earlier SourcePatchFailure umbrella naming is superseded and is not retained as a public alias, because Document-level lifecycle and revision failures are not SourcePatch-operation failures.

[DevilTea]

Migrated comment 109 from DevilTea/deviltea-labs#54 — @DevilTea, 2026-09-01T15:42:54Z
Original: DevilTea/deviltea-labs#54 (comment)

CURRENT / ACCEPTED — implementation freeze checkpoint after canonical consolidation

The #54 issue body has been fully reconsolidated on 2026-09-01 and is now the implementation-ready canonical specification for the non-MCP authored-source / Blueprint / WidgetDocument / SourcePatch / Catalog redesign.

Freeze status

• known pre-implementation public architecture gaps for this redesign are considered closed;
• historical comments remain as audit/decision history, but superseded models must not be reconstructed from them;
• implementation should use the current issue body directly;
• internal implementation choices remain free where the body deliberately leaves representation/mechanics non-normative;
• a new architecture amendment is warranted only for a concrete contradiction, required public semantic change, or proven downstream Core gap.

Scope split

• feat(widget-lab): host Preview Runtime and renderer inside iframe #10 = high-level living Core architecture log;
• #54 = detailed implementation-ready authored document/source mutation contract;
• #55 = Widget MCP integration, canonical there and intentionally deferred;
• persistence/source migration/version management remains application policy outside Core.

Authority going forward

The body is the consolidated baseline. Any future comment that intentionally changes the contract must be explicitly marked CURRENT / ACCEPTED; a later such amendment wins for its stated scope until the body is reconsolidated again.

This checkpoint authorizes proceeding with the non-MCP redesign implementation without further speculative architecture work.

[DevilTea]

Migrated comment 110 from DevilTea/deviltea-labs#54 — @DevilTea, 2026-09-02T03:37:16Z
Original: DevilTea/deviltea-labs#54 (comment)

CURRENT / ACCEPTED — exact-source JSON inspection Diagnostic taxonomy

Implementation review of #56 exposed one concrete gap in the frozen recovery contract: sourceJsonCompatible:false is specified as a fail-closed proof with precise retained Diagnostics, but the public JSON-domain reason taxonomy and unsafe-inspection Diagnostic variant were not fully frozen.

This amendment closes only that gap. All other non-MCP Core architecture remains unchanged.

1. Confirmed JSON-domain violations use json-incompatible-value

Core exposes a framework-owned Blueprint Diagnostic variant conceptually shaped as:

interface JsonCompatibilityDiagnostic
  extends DiagnosticBase<
    'json-incompatible-value',
    { readonly type: 'source' }
  > {
  readonly path: DiagnosticPath
  readonly reason: JsonCompatibilityReason
}

path is rooted at the complete exact authored Blueprint.source. Root failure uses [].

The closed framework-owned reason union is:

type JsonCompatibilityReason =
  | 'undefined'
  | 'non-finite-number'
  | 'bigint'
  | 'symbol'
  | 'function'
  | 'unsupported-object-prototype'
  | 'symbol-key'
  | 'accessor-property'
  | 'sparse-array'
  | 'array-extra-property'
  | 'cyclic-reference'

Semantics:

• undefined — an authored value is undefined.
• non-finite-number — an authored number is NaN, Infinity, or -Infinity.
• bigint — an authored value is a bigint.
• symbol — an authored value is a symbol.
• function — an authored value is callable/function-valued.
• unsupported-object-prototype — an authored object/Array does not have the allowed plain-object / intrinsic-Array prototype. This intentionally covers Date, Map, Set, arbitrary class instances, custom Array subclasses/prototypes, and future analogous object kinds without exposing a built-in-type taxonomy.
• symbol-key — authored own data contains a symbol-keyed property.
• accessor-property — an authored own property is accessor-backed rather than an own data property. Core detects this from descriptors and never invokes the accessor.
• sparse-array — an Array has a missing indexed own data element inside [0, length).
• array-extra-property — an Array has authored own string-keyed material other than its intrinsic length and canonical in-range indexed elements.
• cyclic-reference — traversal encounters an object/Array already active on the current inspection path. Repeated acyclic aliasing across completed sibling paths is not a cycle.

These reasons describe authored-domain semantics, not JavaScript reflection implementation details.

2. Unproven safety uses source-access-failed, not JSON incompatibility

If Core cannot safely inspect a source fragment well enough to establish compatibility or a concrete JSON-domain violation, it emits a distinct framework-owned Blueprint Diagnostic:

interface SourceAccessDiagnostic
  extends DiagnosticBase<
    'source-access-failed',
    { readonly type: 'source' }
  > {
  readonly path: DiagnosticPath
}

path identifies the source-rooted fragment whose inspection could not safely complete; root failure uses [].

Examples include Proxy/reflection behavior that throws or otherwise prevents safe own-key / prototype / descriptor inspection.

This Diagnostic deliberately has no public reason distinguishing ownKeys, getPrototypeOf, getOwnPropertyDescriptor, Array.isArray, or similar reflection mechanics. Those are implementation details with the same machine-actionable recovery semantics.

The string code source-access-failed is intentionally shared with the existing SourcePatch failure vocabulary across different public protocols: Blueprint Diagnostic vs SourcePatch operation Failure. In both protocols the machine meaning is that Core could not safely access authored source. Their surrounding discriminated unions and payloads remain distinct.

An unsafe/unproven fragment must not be relabeled as json-incompatible-value.

3. Inspection aggregation and safety

Whole-source inspection is deterministic and broadly aggregating where safe:

• Core reports independently observable JSON-domain violations across sibling branches rather than stopping after the first violation.
• A confirmed local violation may stop traversal below that value when deeper inspection would not add safely meaningful facts.
• Unsafe inspection uses local-stop semantics for that fragment while traversal may continue through independently safe sibling branches.
• Authored getters/accessors are never executed.
• Diagnostics retain source-rooted paths and are part of the immutable Blueprint diagnostic snapshot.

sourceJsonCompatible remains the existing public boolean proof:

true  → the exact Blueprint source was completely proven inside JsonValue
false → confirmed JSON-domain violation OR proof could not safely complete

The Diagnostic union distinguishes those two causes.

4. Blueprint validity

The existing invariant remains unchanged:

sourceJsonCompatible:false → status:'invalid'

Blueprint status is still not derived generically from Diagnostic count. JSON-domain proof is itself a required authored-source invariant; the new Diagnostic variants retain the concrete failed facts.

Canonical invariant

Exact-source JSON inspection distinguishes confirmed incompatibility from unproven safe access. Confirmed authored-domain violations use json-incompatible-value with a closed semantic JsonCompatibilityReason; inability to safely inspect uses source-access-failed with a source-rooted path and no reflection-mechanics reason. Inspection aggregates independent safe findings, locally stops at unsafe fragments, never executes authored accessors, and leaves sourceJsonCompatible as the fail-closed boolean proof over the exact Blueprint source.

[DevilTea]

Widget Lab and Vue reference integration

Historical Lab/reference-renderer authority.

Historical source: DevilTea/deviltea-labs#13 — Widget Lab architecture — reference renderer and interactive showcases.

The replies below preserve the source issue body and chronological comments as migration history.

[DevilTea]

Migrated comment 36 from DevilTea/deviltea-labs#13 — @DevilTea, 2026-08-16T04:06:56Z
Original: DevilTea/deviltea-labs#13 (comment)

[Claude]

Post-convergence usability/hardening phase (#25–#30) — completed

All six issues of the backlog opened after the Showcase B convergence are implemented, adversarially reviewed (GPT merge gate, review→fix→re-review to explicit PASS on every PR), merged, and closed:

Issue	PRs	Outcome
#29 AGENTS current-state refresh	#31	apps/widget-lab/AGENTS.md is a current-state operating guide
#28 browser contracts + baseline a11y	#32 (+#33/#34 flipped its fixmes)	Playwright suite against the built artifact with external network blocked; CRM table keyboard/aria-current, native-<dialog> modal, label associations
#26 Survey freshness/failure/provenance	#33	resultInputs snapshot State + resultFresh Property (dedicated resultInputQuestionIds), Unavailable metrics, structured per-metric provenance
#27 Graph/workbench recovery	#34	fit-on-nodesInitialized + Fit graph, non-closable canonical panels via tab-content renderer, 900px gate
#30 self-contained deployment	#35	Monaco engine self-hosted via importmap (3 vendored files), modern-monaco/core (LSP side effect removed), offline Source contract; ELK startup-load adjudicated non-blocking
#25 onboarding/tutorial/explorer	#36–#40	gated UX proposal (v1+v2), Survey+CRM staged tours with OWNER-locked deterministic start, Inspect mode (with the useWidget() identity amendment recorded above), curated Implementation explorer (Shiki, lazy), Graph legend + copy pass

Current verification surface on main: 47 unit-test files / 308 tests in widget-lab (plus the root suite at 163 files / 2927+ tests with the coverage gate), and 48 real-browser contracts — all green. Deployed Lab: https://deviltea.github.io/deviltea-labs/widget-lab/

Deferred items already recorded: keyboard-driven Inspect selection (out of P2 scope, documented in-code); ELK tab-view-gated instantiation (optional future performance issue per the #35 adjudication).

One process incident is on record (PR #36 was merged with a red required check; root cause was a racy test assertion, fixed forward in #37 within the hour; merges are now gated programmatically on all-checks-pass).

This issue remains the canonical decision log for whatever the Owner directs next.

[DevilTea]

Migrated comment 37 from DevilTea/deviltea-labs#13 — @DevilTea, 2026-08-16T08:44:54Z
Original: DevilTea/deviltea-labs#13 (comment)

[GPT]

RETRACTED — wrong repository/project.

This comment was posted by mistake while handling a Collab task for the separate PikaCSS project. It is not an instruction for deviltea-labs, should not be acted on, and carries no architectural or implementation authority for this repository.

No repository state or issue status was changed by the mistaken comment.

[DevilTea]

Migrated comment 38 from DevilTea/deviltea-labs#13 — @DevilTea, 2026-08-29T12:58:38Z
Original: DevilTea/deviltea-labs#13 (comment)

Accepted — Vue public API migrates fully from Issue to Diagnostic

@deviltea/widget-vue will migrate its public and internal Issue vocabulary to Diagnostic in one breaking pass, with no deprecated Issue aliases.

Public useWidget() accessors become:

useStateDiagnostics()
usePropertyDiagnostics()
useMethodDiagnostics()
useDiagnostics()

Public type names migrate correspondingly:

UseWidgetStateDiagnosticsSurface
UseWidgetStateDiagnosticsAccessor
UseWidgetPropertyDiagnosticsSurface
UseWidgetPropertyDiagnosticsAccessor
UseWidgetMethodDiagnosticsSurface
UseWidgetMethodDiagnosticsAccessor
UseWidgetDiagnosticsAccessor

Internal bridge vocabulary likewise migrates (createDiagnosticsRef, getDiagnostics, subscribeDiagnostics, etc.). Vue remains a thin projection of Core: failed Property/Method execution still projects to null, Diagnostics remain separate lazy readonly refs, and Core Runtime remains the sole source of truth. ExecutionResult consumption migrates to the accepted Core result.ok protocol.

No Issue-named compatibility aliases are retained; the terminology change is intentionally completed atomically across Core and Vue.

[DevilTea]

Migrated comment 39 from DevilTea/deviltea-labs#13 — @DevilTea, 2026-08-29T13:04:32Z
Original: DevilTea/deviltea-labs#13 (comment)

ACCEPTED — Vue participates in the atomic Issue → Diagnostic migration

@deviltea/widget-vue is migrated in the same breaking pass as Core; no Issue-named compatibility aliases are retained.

Public useWidget() surface:

• useStateIssues() → useStateDiagnostics()
• usePropertyIssues() → usePropertyDiagnostics()
• useMethodIssues() → useMethodDiagnostics()
• useIssues() → widget-aggregate useDiagnostics()
• corresponding UseWidget*Issues* public types → UseWidget*Diagnostics*

Internal bridge vocabulary also migrates (createIssuesRef → createDiagnosticsRef, getIssues/subscribeIssues → getDiagnostics/subscribeDiagnostics, local variable/comment terminology, etc.). Vue continues forwarding Core snapshots lazily with Core as the sole source of truth.

The same pass updates Core Result consumption from result.success / result.issues to result.ok / result.failure.diagnostics. Projection policy does not change: failed Property/Method execution still projects to null, while diagnostics remain separately reactive.

Migration scope includes Vue source, tests, type tests, examples, and maintained documentation/comments. Completion means maintained Vue integration code contains no semantic Issue API or superseded success/issues Result vocabulary except explicit historical migration discussion.

[DevilTea]

Migrated comment 40 from DevilTea/deviltea-labs#13 — @DevilTea, 2026-08-29T13:14:20Z
Original: DevilTea/deviltea-labs#13 (comment)

CURRENT — Vue package follows shared Widget API/DX conventions document

Accepted documentation ownership after the Diagnostic/Result DX audit.

@deviltea/widget-vue shares the cross-package normative conventions maintained at:

docs/architecture/widget-api-conventions.md

Issue #13 remains Vue architecture decision history/rationale. Vue package README/AGENTS documentation should reference the shared conventions document rather than duplicate vocabulary/protocol rules. Vue-specific renderer/integration semantics remain documented in the Vue package/#13; shared Diagnostic/Result/Error/naming conventions remain centralized.

[DevilTea]

Widget MCP integration

Deferred MCP architecture; preserved without implying implementation is resumed.

Historical source: DevilTea/deviltea-labs#55 — design: Widget MCP integration — AI live document editing adapter.

The replies below preserve the source issue body and chronological comments as migration history.

[DevilTea]

Migrated from DevilTea/deviltea-labs#55 — original body

Purpose

Canonical continuation for Widget MCP integration architecture, split out from #54 so Core / authored-document decisions can converge and land independently.

This issue is intentionally DEFERRED / PAUSED for now. Do not implement Widget MCP until this issue is resumed.

Scope

@deviltea/widget-mcp is an AI-facing adapter over one host-owned live WidgetSystem + WidgetDocument pair.

Its purpose is to let an MCP-capable AI precisely:

• understand the available Widget authoring language;
• inspect the current live WidgetDocument;
• diagnose invalid/recovered source;
• repair or author source;
• apply precise low-level edits with optimistic-concurrency protection;
• stay fresh when the live Document changes.

It is not a persistence or document-management layer.

Out of scope for Widget MCP:

• source persistence / save / load / save-as;
• authored-source migration/version management;
• file paths or workspace/project management;
• document libraries/discovery;
• history / undo / redo;
• autosave / database ownership;
• Runtime-state persistence;
• rendering/deployment;
• multi-document ownership/routing in integration v1.

Persistence and authored-source version/migration policy belong to the application layer using @deviltea/widget-core.

Canonical ownership / authority

• feat(widget-lab): host Preview Runtime and renderer inside iframe #10 remains the canonical high-level Widget composition architecture log.
• #54 remains canonical for Core authored-source / Blueprint / WidgetDocument / mutation / representation architecture.
• This issue is canonical for Widget MCP integration from this split onward.
• Existing explicit CURRENT / ACCEPTED MCP decisions in #54 are imported below and remain binding unless explicitly superseded here.

Imported CURRENT / ACCEPTED MCP decisions from #54

Product / boundary

• MCP exists to let AI accurately understand, inspect, diagnose, repair, author, and edit one live host-owned WidgetDocument.
• widget://catalog describes the System authoring language.
• widget://document projects the current coherent Document state.
• apply_patch performs precise structural mutation.
• revision / expectedRevision protects delayed AI read→decide→write flows.
• document-update notifications are cache invalidations, not persisted state or an event log.

Origin: #54 comment 5495392174.

Universal eligibility / current-source transport branch

• every WidgetSystem is MCP-eligible;
• no Plugin/System JSON-capability gate exists;
• full vs degraded document projection depends only on current Blueprint sourceJsonCompatible;
• sourceJsonCompatible:true permits exact JSON source transport even when semantically invalid;
• sourceJsonCompatible:false uses degraded recovery projection and does not transport exact source.

Origin: #54 5486904419.

Resource projection

• widget://catalog and widget://document are separate resources;
• widget://document is one coherent projection of one Document snapshot;
• mutable correlated facts are not split into independently-read resources;
• raw Blueprint objects are not transported;
• degraded recovery uses recovered nodes / source pointers rather than duplicate full structural projection;
• recovered root is identified by sourcePointer === '';
• recovered nodes use a resolved discriminated union.

Origins: #54 5487697015, 5487805610, 5487924082.

Mutation

• MCP apply_patch requires expectedRevision on every request even though Core supports an unguarded local call;
• result keeps both changed and resulting revision because they answer different questions;
• expected Core mutation failures remain model-recoverable tool failures rather than protocol/server errors.

Origins include #54 5489381189, 5495075382.

Binding lifetime / ownership

• one live binding is permanently fixed to one concrete WidgetDocument instance;
• host/application owns WidgetSystem and WidgetDocument;
• binding is a disposable adapter and does not destroy either domain object;
• v1 binding is single-document;
• binding construction receives explicit System + Document and verifies exact origin-System instance identity;
• replacing/recreating a Document requires a new binding/resource/session identity rather than silent rebinding.

Origins: #54 5489558630, 5491616914, 5492248886.

SDK / protocol baseline

• implementation uses official TypeScript MCP SDK v2 only;
• architecture is modern-first against protocol 2026-07-28;
• 2025-era legacy wire compatibility may be served through SDK-v2 compatibility mechanisms;
• no SDK-v1 implementation is maintained;
• legacy transport mechanics do not shape Widget domain architecture.

Origin: #54 5492613721.

Document update semantics

• document changes publish resource invalidation, not snapshot push;
• tool response and resource update have no cross-channel ordering guarantee;
• mutation initiator receives the same invalidation as other subscribed clients;
• response revision means the revision committed by that operation, not necessarily current-at-observation;
• pending invalidations may coalesce, but once published, later commits must create a new pending invalidation;
• clients needing continuous freshness establish update subscription/listen first, wait until active, then take baseline widget://document read;
• after subscription loss/recreation, cached state is potentially stale and must be re-read after subscription is re-established;
• no replay cursor / event log is added.

Origins: #54 5492420770, 5492443338, 5492625630, 5493894561.

Shutdown / cancellation

• binding close uses graceful drain semantics;
• closing stops admission of new requests/subscriptions;
• already-admitted operations may complete;
• once execution crosses into synchronous Core WidgetDocument.applyPatch(), binding shutdown or transport cancellation does not interrupt/roll back it;
• cancellation may prevent entry into that atomic Core boundary.

Origin: #54 5494736965.

Deferred / not accepted

The resource MIME/schema-version discussion was not accepted before this split. Current direction was leaning toward ordinary application/json live projections with no independently persisted MCP schema state, but this remains OPEN when MCP work resumes.

Resume condition

Resume this issue only after the non-MCP Core / Document architecture targeted by #10 / #54 has converged and the current redesign has landed.

[DevilTea]

Provider-style / descendant-scoped dependency semantics

Active bounded design/work remains in DevilTea/widget#3 — design(core): descendant-scoped dependency target for provider-style widgets.

Keep implementation-specific exploration there while it is active. Once a durable architectural decision is accepted, record the accepted direction in this topic so this Discussion remains the long-term authority.

[DevilTea]

Preview isolation and Inspector/DevTools transport

Active bounded design/work remains in DevilTea/widget#5 — design(widget-lab): isolate Preview and define an extension-ready inspector transport.

Keep implementation-specific exploration there while it is active. Once a durable architectural decision is accepted, record the accepted direction in this topic so this Discussion remains the long-term authority.