diff --git a/apps/demo/src/batch-main.ts b/apps/demo/src/batch-main.ts
index 1c2e16e..f64b841 100644
--- a/apps/demo/src/batch-main.ts
+++ b/apps/demo/src/batch-main.ts
@@ -197,7 +197,7 @@ function makeTile(prompt: string, tokensCss: string, interactivity: Interactivit
if (handleRef.current) handleRef.current.pushState(state);
},
onHandlerError: (intent, error) => {
- markIntent(`handler error (${intent}): ${error.message}`, true);
+ markIntent(`host handler error (${intent}): ${error.message}`, true);
},
});
}
@@ -223,7 +223,7 @@ function makeTile(prompt: string, tokensCss: string, interactivity: Interactivit
void policy?.dispatch(intent, args);
},
onIntentRejected: (reason) => {
- intentEl.textContent = `rejected: ${reason}`;
+ intentEl.textContent = `request rejected: ${reason}`;
intentEl.classList.add('on', 'err');
},
});
diff --git a/apps/demo/src/generate-main.ts b/apps/demo/src/generate-main.ts
index b6a1bd3..4db3fee 100644
--- a/apps/demo/src/generate-main.ts
+++ b/apps/demo/src/generate-main.ts
@@ -243,7 +243,7 @@ function describeScenario(scenario: ShowcaseScenario): ScenarioPresentation {
if (scenario.id.startsWith('ghost-')) {
return {
category: 'Ghost',
- description: 'Environment-specific Ghost memory root with host-granted controls.',
+ description: 'Environment-specific Ghost memory root with host-allowed controls.',
};
}
switch (scenario.id) {
@@ -300,23 +300,41 @@ function describeScenario(scenario: ShowcaseScenario): ScenarioPresentation {
case 'sibling-summon':
return {
category: 'Composition',
- description: 'Parent surface can summon a sibling sandbox with narrowed grants.',
+ description: 'Parent surface can summon a sibling sandbox with narrowed host tools.',
};
case 'repair-diagnostics':
return {
category: 'Diagnostics',
- description: 'Repair-enabled generation with validation and retry diagnostics.',
+ description: 'Validation retry generation with diagnostics.',
};
default:
return {
category: 'Showcase',
- description: 'Contract-accurate Summon generation scenario.',
+ description: 'Surface-configured Summon generation scenario.',
};
}
}
function compactPlanText(plan: SurfacePlan): string {
- return `${plan.purpose} · ${plan.runtime} · ${plan.data} · ${plan.authority}`;
+ return [
+ displayPlanPart(plan.purpose),
+ displayPlanPart(plan.runtime),
+ displayPlanPart(plan.data),
+ displayPlanPart(plan.authority),
+ ].join(' · ');
+}
+
+function displayPlanPart(value: string): string {
+ switch (value) {
+ case 'host-resource':
+ return 'host data';
+ case 'host-action':
+ return 'host action';
+ case 'approval-gated':
+ return 'approval required';
+ default:
+ return value.replace(/-/g, ' ');
+ }
}
function paintStatus() {
@@ -431,7 +449,7 @@ function renderScenarioLibrary() {
desc.textContent = presentation.description;
const meta = document.createElement('span');
meta.className = 'scenario-card-meta';
- meta.textContent = `${compactPlanText(scenario.surfacePlan)} · ${scenario.capabilityNames.length} grants`;
+ meta.textContent = `${compactPlanText(scenario.surfacePlan)} · ${scenario.capabilityNames.length} host tools`;
card.append(title, desc, meta);
card.addEventListener('click', () => selectScenario(scenario.id));
group.append(card);
@@ -457,7 +475,7 @@ function updateScenarioPresentation(scenario: ShowcaseScenario) {
scenarioActiveFingerprintEl.textContent = compactPlanText(scenario.surfacePlan);
const componentCount = scenario.componentNames?.length ?? 0;
scenarioActiveGrantsEl.textContent =
- `${scenario.capabilityNames.length} grants${componentCount ? ` · ${componentCount} components` : ''}`;
+ `${scenario.capabilityNames.length} host tools${componentCount ? ` · ${componentCount} trusted components` : ''}`;
welcomeTextEl.textContent = `${scenario.label} awaits generated UI.`;
updateSelectedScenarioCard();
}
@@ -566,14 +584,20 @@ function hasDirectionOption(value: string): boolean {
return Array.from(directionSel.options).some((opt) => opt.value === value);
}
-function planText(plan: SurfacePlan): string {
- return `${plan.purpose}/${plan.runtime}/${plan.data}/${plan.authority}/${plan.persistence}`;
+function planText(plan: { purpose: string; runtime: string; data: string; authority: string; persistence: string }): string {
+ return [
+ displayPlanPart(plan.purpose),
+ displayPlanPart(plan.runtime),
+ displayPlanPart(plan.data),
+ displayPlanPart(plan.authority),
+ displayPlanPart(plan.persistence),
+ ].join(' · ');
}
function renderContractSummary() {
const active = readActiveContract();
const requested = active.surfacePlan;
- const grants = active.capabilityNames.length ? active.capabilityNames.join(', ') : 'none';
+ const hostTools = active.capabilityNames.length ? active.capabilityNames.join(', ') : 'none';
const components = active.componentNames?.length ? active.componentNames.join(', ') : 'none';
const validation = currentValidationSummary ?? 'pending';
const stream = currentStreamHealth ?? 'pending';
@@ -581,14 +605,14 @@ function renderContractSummary() {
inspectorStatusEl.textContent = currentEffectiveSurfacePlan ? 'effective' : 'pending';
contractSummaryEl.innerHTML = '';
const rows = [
- ['requested', 'Requested Plan', planText(requested), 'neutral'],
- ['effective', 'Effective Plan', effective, currentEffectiveSurfacePlan ? 'good' : 'pending'],
- ['grants', 'Grants', `${active.capabilityNames.length}: ${grants}`, active.capabilityNames.length ? 'neutral' : 'pending'],
- ['components', 'Components', `${active.componentNames?.length ?? 0}: ${components}`, active.componentNames?.length ? 'good' : 'pending'],
+ ['requested', 'Requested surface config', planText(requested), 'neutral'],
+ ['effective', 'Effective safety plan', effective, currentEffectiveSurfacePlan ? 'good' : 'pending'],
+ ['grants', 'Allowed host tools', `${active.capabilityNames.length}: ${hostTools}`, active.capabilityNames.length ? 'neutral' : 'pending'],
+ ['components', 'Trusted components', `${active.componentNames?.length ?? 0}: ${components}`, active.componentNames?.length ? 'good' : 'pending'],
['runtime', 'Runtime', `${active.mode} · scripts ${active.scriptPolicy}`, active.scriptPolicy === 'allow' ? 'warn' : 'neutral'],
['validation', 'Validation', validation, validation !== 'pending' && !validation.startsWith('0/') ? 'warn' : validation === 'pending' ? 'pending' : 'good'],
- ['stream', 'StreamGraph', stream, stream.startsWith('complete') ? 'good' : stream === 'pending' ? 'pending' : 'warn'],
- ['repair', 'Repair', active.repair?.enabled ? (currentRepairSummary ?? 'on') : 'off', active.repair?.enabled ? 'warn' : 'pending'],
+ ['stream', 'Stream diagnostics', stream, stream.startsWith('complete') ? 'good' : stream === 'pending' ? 'pending' : 'warn'],
+ ['repair', 'Validation retry', active.repair?.enabled ? (currentRepairSummary ?? 'on') : 'off', active.repair?.enabled ? 'warn' : 'pending'],
['tokens', 'Tokens', active.tokenOverrides ? 'override' : 'base', active.tokenOverrides ? 'good' : 'pending'],
['shape', 'Shape', currentShape ?? 'pending', currentShape ? 'neutral' : 'pending'],
] as const;
@@ -641,7 +665,7 @@ function summarizeStreamGraphMeta(value: unknown): string {
const missing = Array.isArray(summary?.health?.missingDeclared) ? summary.health.missingDeclared.length : 0;
const blocked = typeof summary?.health?.blockedCount === 'number' ? summary.health.blockedCount : 0;
const repaired = typeof summary?.health?.repairedCount === 'number' ? summary.health.repairedCount : 0;
- return `${complete ? 'complete' : 'open'} m=${missing} b=${blocked} r=${repaired}`;
+ return `${complete ? 'complete' : 'open'} · missing=${missing} blocked=${blocked} retried=${repaired}`;
}
function applyTokenOverrideCss(baseCss: string, applied: Array<{ token: string; value: string }>): string {
@@ -713,7 +737,7 @@ async function loadDirections(): Promise
{
}
if (ghostRoots.length > 0) {
const group = document.createElement('optgroup');
- group.label = 'Ghost intent';
+ group.label = 'Ghost steering';
for (const root of ghostRoots) {
const opt = document.createElement('option');
opt.value = ghostSelectionValue(root.id);
@@ -791,9 +815,9 @@ function tokensFor(directionId: string | null): string {
}
/**
- * Respawn the sandbox with the right tokens and the right intent policy for
+ * Respawn the sandbox with the right tokens and the right host tool policy for
* the current mode. Interactive mode binds a fresh PolicyEngine with the 3
- * canned handlers; static mode has no intents.
+ * canned handlers; static mode has no host tools.
*/
function respawn(
directionId: string | null,
@@ -855,7 +879,7 @@ function respawn(
if (handle) handle.pushState(state);
},
onHandlerError: (intent, err) => {
- logLine('op-error', `handler error (${intent}): ${err.message}`);
+ logLine('op-error', `host handler error (${intent}): ${err.message}`);
},
events,
});
@@ -1132,12 +1156,12 @@ function applyLineTo(target: SandboxTarget, line: ProtocolLine, context: Surface
}
if (line.op === 'meta' && line.path === '/repair-summary') {
target.onRepairSummary?.(line.value);
- target.onLog('op-meta', `repair → ${JSON.stringify(line.value)}`);
+ target.onLog('op-meta', `validation retry → ${JSON.stringify(line.value)}`);
return;
}
if (line.op === 'meta' && line.path === '/stream-graph-summary') {
target.onStreamGraphSummary?.(line.value);
- target.onLog('op-meta', `stream graph → ${JSON.stringify(line.value)}`);
+ target.onLog('op-meta', `stream diagnostics → ${JSON.stringify(line.value)}`);
return;
}
if (line.op === 'meta' && line.path === '/status') {
@@ -1490,8 +1514,8 @@ function renderSavedSurfaces() {
const validation = item.validationIssues.length;
const complete = item.streamGraph?.health.complete ? 'complete' : 'open';
meta.textContent =
- `${plan.purpose}/${plan.runtime}/${plan.data}/${plan.authority}` +
- ` · grants=${item.grants.intents.length}` +
+ `${compactPlanText(plan)}` +
+ ` · hostTools=${item.grants.intents.length}` +
` · validation=${validation}` +
` · ${complete}` +
` · ${new Date(item.createdAt).toLocaleTimeString()}`;
@@ -1517,7 +1541,7 @@ function replaySurface(envelope: SurfaceEnvelope) {
currentShape = envelope.metadata.shape ?? null;
currentValidationSummary = `${envelope.validationIssues.filter((issue) => issue.severity === 'block').length}/${envelope.validationIssues.filter((issue) => issue.severity === 'warn').length}`;
currentStreamHealth = envelope.streamGraph
- ? `${envelope.streamGraph.health.complete ? 'complete' : 'open'} m=${envelope.streamGraph.health.missingDeclared.length} b=${envelope.streamGraph.health.blockedCount} r=${envelope.streamGraph.health.repairedCount}`
+ ? `${envelope.streamGraph.health.complete ? 'complete' : 'open'} · missing=${envelope.streamGraph.health.missingDeclared.length} blocked=${envelope.streamGraph.health.blockedCount} retried=${envelope.streamGraph.health.repairedCount}`
: null;
acc.reset();
for (const line of envelope.protocolLines) {
@@ -1585,7 +1609,7 @@ async function generate(prompt: string) {
if (!currentRepairSummary) currentRepairSummary = active.repair?.enabled ? '0/0' : 'off';
if (!currentStreamHealth) {
currentStreamHealth =
- `${result.streamGraph.health.complete ? 'complete' : 'open'} m=${result.streamGraph.health.missingDeclared.length} b=${result.streamGraph.health.blockedCount} r=${result.streamGraph.health.repairedCount}`;
+ `${result.streamGraph.health.complete ? 'complete' : 'open'} · missing=${result.streamGraph.health.missingDeclared.length} blocked=${result.streamGraph.health.blockedCount} retried=${result.streamGraph.health.repairedCount}`;
}
renderContractSummary();
saveSurfaceEnvelope(prompt, result);
@@ -1643,7 +1667,7 @@ async function editArtifact(instruction: string) {
});
if (!currentStreamHealth) {
currentStreamHealth =
- `${result.streamGraph.health.complete ? 'complete' : 'open'} m=${result.streamGraph.health.missingDeclared.length} b=${result.streamGraph.health.blockedCount} r=${result.streamGraph.health.repairedCount}`;
+ `${result.streamGraph.health.complete ? 'complete' : 'open'} · missing=${result.streamGraph.health.missingDeclared.length} blocked=${result.streamGraph.health.blockedCount} retried=${result.streamGraph.health.repairedCount}`;
}
renderContractSummary();
currentStatus = 'done';
@@ -1674,7 +1698,7 @@ async function editArtifact(instruction: string) {
* - its own AbortController (close = abort + dispose)
*
* Depth cap of 1: children get every demo intent EXCEPT `summon`, so a
- * grandchild generation can't cascade. Easy to relax (counter on grants),
+ * grandchild generation can't cascade. Easy to relax (counter on allowed tools),
* but avoids accidental fan-out for the demo.
*/
function summonChild(childPrompt: string, title?: string) {
@@ -1710,7 +1734,7 @@ function summonChild(childPrompt: string, title?: string) {
let childHandle: SandboxHandle | null = null;
let childTokensSourceOverride: string | null = activeTokensSourceOverride;
- // Grants are narrowed: every demo intent EXCEPT summon. This is the
+ // Allowed tools are narrowed: every demo intent EXCEPT summon. This is the
// depth-cap mechanism — the trust boundary is the bridge allowlist, not
// the LLM's word.
const childCapabilityNames = baseCapabilityPack.intents
@@ -1733,7 +1757,7 @@ function summonChild(childPrompt: string, title?: string) {
if (childHandle) childHandle.pushState(state);
},
onHandlerError: (intent, err) => {
- statusEl.textContent = `handler error (${intent}): ${err.message.slice(0, 40)}`;
+ statusEl.textContent = `host handler error (${intent}): ${err.message.slice(0, 40)}`;
},
events,
});
@@ -1838,20 +1862,20 @@ updateEditControls();
function summarize(ev: DevtoolsEvent): string {
switch (ev.kind) {
case 'sandbox-spawned':
- return `${ev.sandboxId.slice(0, 8)}… grants=[${ev.grantedIntents.join(',') || '—'}]`;
+ return `${ev.sandboxId.slice(0, 8)}… allowed=[${ev.grantedIntents.join(',') || '—'}]`;
case 'sandbox-ready':
case 'sandbox-disposed':
return `${ev.sandboxId.slice(0, 8)}…`;
case 'sandbox-fatal':
return `${ev.sandboxId.slice(0, 8)}… ${ev.reason}`;
case 'intent-emitted':
- return `${ev.intent} ${JSON.stringify(ev.args).slice(0, 80)}`;
+ return `host tool ${ev.intent} ${JSON.stringify(ev.args).slice(0, 80)}`;
case 'intent-rejected':
return `${ev.reason}`;
case 'intent-dispatched':
- return `${ev.intent} #${ev.id.slice(-6)}`;
+ return `host dispatch ${ev.intent} #${ev.id.slice(-6)}`;
case 'intent-settled':
- return `${ev.intent} #${ev.id.slice(-6)} ${ev.ok ? 'ok' : `fail: ${ev.error ?? ''}`} (${ev.durationMs}ms)`;
+ return `host settled ${ev.intent} #${ev.id.slice(-6)} ${ev.ok ? 'ok' : `fail: ${ev.error ?? ''}`} (${ev.durationMs}ms)`;
case 'state-pushed':
return Object.keys(ev.patch).join(', ') || '∅';
case 'protocol-line':
@@ -1861,13 +1885,13 @@ function summarize(ev: DevtoolsEvent): string {
case 'stream-lifecycle':
return ev.phase === 'start' ? 'start' : `end ok=${ev.ok}`;
case 'stream-graph':
- return `sections=${ev.sections.length} missing=${ev.health.missingDeclared.length} skipped=${ev.health.skippedCount} repaired=${ev.health.repairedCount}`;
+ return `sections=${ev.sections.length} missing=${ev.health.missingDeclared.length} skipped=${ev.health.skippedCount} retried=${ev.health.repairedCount}`;
case 'surface-plan':
- return `${ev.plan.purpose}/${ev.plan.runtime}/${ev.plan.data}/${ev.plan.authority}/${ev.plan.persistence}`;
+ return planText(ev.plan);
case 'render':
return `${ev.bytes.toLocaleString()} B`;
case 'component-sync':
- return `${ev.components.length} island${ev.components.length === 1 ? '' : 's'}`;
+ return `${ev.components.length} trusted component${ev.components.length === 1 ? '' : 's'}`;
case 'component-error':
return `${ev.componentName ?? ev.componentId ?? 'component'} ${ev.code ?? 'error'}: ${ev.reason}`;
}
@@ -1891,7 +1915,7 @@ function paintDevtools() {
for (const ev of snap) counts[ev.kind] = (counts[ev.kind] ?? 0) + 1;
const tally = Object.entries(counts)
.sort((a, b) => b[1] - a[1])
- .map(([k, v]) => `${k.replace(/^(intent|sandbox|protocol|stream)-/, '')} ${v}`)
+ .map(([k, v]) => `${displayEventKind(k)} ${v}`)
.join(' · ');
devtoolsTally.textContent = tally;
@@ -1916,6 +1940,23 @@ function paintDevtools() {
devtoolsLog.scrollTop = devtoolsLog.scrollHeight;
}
+function displayEventKind(kind: string): string {
+ switch (kind) {
+ case 'intent-emitted':
+ return 'host tool';
+ case 'intent-rejected':
+ return 'request rejected';
+ case 'intent-dispatched':
+ return 'host dispatch';
+ case 'intent-settled':
+ return 'host settled';
+ case 'stream-graph':
+ return 'stream diagnostics';
+ default:
+ return kind.replace(/^(sandbox|protocol|stream)-/, '').replace(/-/g, ' ');
+ }
+}
+
events.subscribe(() => {
// Coalesce bursts (one streaming run can fire dozens of events per tick)
// into a single repaint per microtask.
diff --git a/apps/demo/src/showcase.ts b/apps/demo/src/showcase.ts
index 9315b42..84243bd 100644
--- a/apps/demo/src/showcase.ts
+++ b/apps/demo/src/showcase.ts
@@ -47,7 +47,7 @@ export interface ActiveContract {
export const SHOWCASE_SCENARIOS: ShowcaseScenario[] = [
{
id: 'host-resource-search',
- label: 'Host-resource search',
+ label: 'Host Data Search',
prompt:
'help me build a weeknight dinner finder where i can search for recipes and see loading, error, and real host data states clearly',
mode: 'interactive',
@@ -92,7 +92,7 @@ export const SHOWCASE_SCENARIOS: ShowcaseScenario[] = [
},
{
id: 'component-islands',
- label: 'Component islands',
+ label: 'Trusted Components',
prompt:
'build a compact launch-readiness dashboard that uses host-rendered component islands for the key metrics, a sparkline, and the approval gate while writing the surrounding analysis and actions yourself',
mode: 'interactive',
@@ -152,7 +152,7 @@ export const SHOWCASE_SCENARIOS: ShowcaseScenario[] = [
},
{
id: 'approval-publish',
- label: 'Approval-gated publish',
+ label: 'Approval Publish',
prompt:
'build a publish approval panel where i can review a titled summary, request host approval, and show pending, approved, denied, and error states',
mode: 'interactive',
@@ -234,9 +234,9 @@ export const SHOWCASE_SCENARIOS: ShowcaseScenario[] = [
},
{
id: 'repair-diagnostics',
- label: 'Repair diagnostics',
+ label: 'Validation Retry Diagnostics',
prompt:
- 'build a compact onboarding checklist with validated submit controls and clear section structure; if a section is rejected, repair it within the same section',
+ 'build a compact onboarding checklist with validated submit controls and clear section structure; if a section is rejected, retry it within the same section',
mode: 'interactive',
capabilityNames: ['submit'],
repair: { enabled: true, maxAttempts: 1, maxTargets: 2 },
@@ -255,7 +255,7 @@ export function createGhostShowcaseScenario(rootId: string): ShowcaseScenario {
id: `ghost-${rootId}`,
label: `Ghost steer: ${rootId}`,
prompt:
- 'generate a compact review surface that follows this Ghost memory root and keeps all controls host-granted',
+ 'generate a compact review surface that follows this Ghost memory root and keeps all controls host-allowed',
mode: 'interactive',
capabilityNames: ['choose', 'log'],
surfacePlan: {
diff --git a/apps/demo/src/strict-main.ts b/apps/demo/src/strict-main.ts
index f14bf91..d36ff50 100644
--- a/apps/demo/src/strict-main.ts
+++ b/apps/demo/src/strict-main.ts
@@ -173,7 +173,7 @@ policy = new PolicyEngine({
handle.pushState(state);
},
onHandlerError: (intent, err) => {
- line('fail', `✗ handler error (${intent}): ${err.message}`);
+ line('fail', `✗ host handler error (${intent}): ${err.message}`);
},
});
@@ -192,11 +192,11 @@ handle = spawnSandbox({
},
onIntentRejected: (reason, raw) => {
const intent = (raw as { intent?: string }).intent ?? '?';
- line('fail', `✗ bridge rejected intent "${intent}": ${reason}`);
+ line('fail', `✗ request rejected "${intent}": ${reason}`);
},
});
line(
'info',
- `Sandbox spawned (${handle.sandboxId.slice(0, 8)}…). Granted: ${policy.intents.join(', ')}`,
+ `Sandbox spawned (${handle.sandboxId.slice(0, 8)}…). Allowed host tools: ${policy.intents.join(', ')}`,
);
diff --git a/docs/adoption/debugging.md b/docs/adoption/debugging.md
index 5ebd39d..00af365 100644
--- a/docs/adoption/debugging.md
+++ b/docs/adoption/debugging.md
@@ -1,25 +1,137 @@
# Summon Debugging Guide
-Summon diagnostics are contract-first. Start with the protocol stream, then use
-Devtools and `StreamGraph` to see whether the generated UI stayed inside the
-declared adoption path.
+Summon diagnostics explain why a generated surface failed, why a generated
+control did nothing, or why host-owned data/components did not appear. Start
+from the symptom, then drill into protocol paths and Devtools events only as
+needed.
-## Diagnostic Layers
+## Generation Failed
+
+Open the **Stream** drawer on `/generate.html` and check:
+
+- `/error` - server-side generation error or blocked-generation message.
+- `/validation-blocked` - a blocking issue stopped generation or validation
+ retry.
+- `/validation-summary` - grouped validation issue counts and examples.
+- `/repair-feedback` - model-readable validation retry hints for a rejected
+ section.
+- `/repair-summary` - counts of queued, cancelled, retried, and failed repairs.
+
+Common fixes:
+
+- `external-url` - inline assets as data URLs or remove the reference.
+- `unsafe-tag` - remove iframe, object, embed, link, meta, or base-like tags.
+- `inline-handler` - use `data-summon-on-*` or scoped `addEventListener`.
+- `static-script` - remove scripts or choose an interactive surface config.
+- `script-not-granted` - use only declarative `data-summon-*` bindings, or
+ select `SurfacePolicy.tier: "scripted"` for a scripted surface type.
+- `surface-policy-*` - fix the host-selected surface config. The compiler
+ blocks unknown allowed tools/components and authority above the selected
+ surface type before the model is called.
+
+## Generated Control Did Nothing
+
+Generated controls request host tools through the sandbox bridge. If a control
+does not work:
+
+1. Confirm the run is interactive. Read-only surfaces intentionally have no
+ allowed host tools.
+2. Confirm the host tool exists in `createCapabilityRegistry(...).toContract()`.
+3. Confirm the generated markup uses an allowed trigger and valid
+ `data-summon-args`.
+4. Check Devtools for `intent-rejected`, `intent-dispatched`,
+ `intent-settled`, and `state-pushed`. The event names still use the runtime
+ term "intent"; read them as host tool requests.
+5. Check the host handler in `PolicyEngine` and the resource's `stateKeys`.
+
+Common fixes:
+
+- `unknown-intent` - use only host tools listed in the Capabilities block.
+- `invalid-args-json` - make `data-summon-args` a valid one-line JSON object.
+- `surface-runtime-exceeded` - use only tools allowed by the compiled safety
+ plan runtime.
+- `surface-data-exceeded` - align resource/worker usage with the selected
+ surface config.
+- `surface-authority-exceeded` - remove the action or select a config that
+ carries the needed authority, such as `approval-gated`.
+
+## Host Tool Returned No Visible Data
+
+Data resources must render loading, error, and data states. If the host handler
+runs but the surface looks empty:
+
+1. Confirm `defineDataResource` has `defaultData` that matches `resultSchema`.
+2. Confirm `stateKeys.loading`, `stateKeys.data`, and `stateKeys.error` are all
+ present.
+3. Confirm generated markup includes visible loading, error, and data bindings.
+4. Trigger the resource and inspect `state-pushed` for the resource state patch.
+
+Common fixes:
+
+- `resource-loading-not-rendered` - render a visible loading binding.
+- `resource-error-not-rendered` - render a visible error binding.
+- `resource-data-not-rendered` - render a visible data binding or foreach.
+
+## Trusted Component Did Not Appear
+
+Trusted host components render as host overlays. If a component placeholder
+remains visible or nothing appears:
+
+1. Confirm the host registered the component and passed
+ `componentRegistry.toContract().pack` into generation.
+2. Confirm replay data includes compatible component allowlists for the same host
+ registry.
+3. Check the Stream drawer for `unknown-component`,
+ `component-props-invalid`, `nested-component`, and compiled safety plan
+ issues.
+4. Check Devtools for `component-sync` followed by `component-error`.
+5. Use the `component-error` code to narrow the fix: `bounds-invalid` means the
+ placeholder has empty/offscreen/oversized bounds, `props-invalid` means Zod
+ rejected the props, and `registry-missing` means replay has component allowlists
+ but the host did not provide a compatible registry.
+6. Confirm host-side Zod validation accepts the props before looking at the
+ component renderer.
+
+Common fixes:
+
+- `unknown-component` - use only names from the Components prompt block.
+- `component-missing-name` - remove stray component id/props attributes or add
+ `data-summon-component`.
+- `component-id-missing` / `component-id-invalid` / `component-id-duplicate` -
+ give every placeholder one stable, unique id such as `revenue-card`.
+- `component-props-missing` / `component-props-invalid` - make
+ `data-summon-props` a valid one-line JSON object.
+- `nested-component` - keep component placeholders as siblings in the freeform
+ layout; do not put one placeholder inside another.
+
+## Sandbox Safety Looks Suspect
+
+1. Run `pnpm test:safety`.
+2. If it fails, inspect the Playwright trace/screenshot.
+3. For manual inspection, run `pnpm dev:all` and open
+ `http://localhost:5173/adversarial.html`.
+4. Confirm network, storage, parent DOM, and unallowed host tool request checks
+ still pass.
+5. Inspect `spawnSandbox` before changing iframe sandbox attributes or CSP.
+
+## Advanced Diagnostic Layers
+
+These names are useful when maintaining Summon or writing a deeper adapter:
1. **Protocol parsing** - `parseProtocolLine` accepts only JSONL protocol
records. Bad raw lines become client-side `protocol-parse-error` events.
2. **Contract validation** - unsafe tags, external URLs, inline handlers,
- unknown intents, bad args JSON, missing resource states, token drift, and
- layout violations become `ContractIssue` records.
-3. **Repair feedback** - retryable section failures can emit
+ unknown host tool requests, bad args JSON, missing resource states, token
+ drift, and layout violations become `ContractIssue` records.
+3. **Validation retry feedback** - retryable section failures can emit
`/repair-feedback` and later `/repair-summary`.
-4. **Stream health** - `StreamGraph` tracks declared, present, skipped,
+4. **Stream diagnostics** - `StreamGraph` tracks declared, present, skipped,
blocked, repaired, and missing sections.
-5. **Policy dispatch** - `PolicyEngine` validates args, runs host handlers,
- emits state patches, and reports handler errors.
-6. **Component islands** - the sandbox reports placeholder bounds, then the
- host validates registered component names and props before rendering overlay
- DOM.
+5. **Host dispatch** - `PolicyEngine` validates args, runs host handlers, emits
+ state patches, and reports handler errors.
+6. **Trusted component overlays** - the sandbox reports placeholder bounds, then
+ the host validates registered component names and props before rendering
+ overlay DOM.
7. **Sandbox boundary** - `spawnSandbox` keeps the iframe null-origin and emits
fatal or rejection signals when the boundary is misconfigured or abused.
@@ -27,23 +139,20 @@ declared adoption path.
| Path | Meaning |
| --- | --- |
-| `/surface-policy` | Host-owned public tier/grants/components/purpose/persistence policy selected for this run. |
-| `/surface-plan` | Host-owned purpose/runtime/data/authority/persistence plan selected for this run. |
+| `/surface-policy` | Host-owned public surface config selected for this run. |
+| `/surface-plan` | Host-owned compiled safety plan selected for this run. |
| `/shape` | Optional server-inferred response shape used to narrow direction exemplars. |
| `/token-overrides` | Resolved direction token overrides, including applied and rejected entries. |
| `/validation-summary` | Final grouped `ContractIssue` counts and examples. |
-| `/validation-blocked` | A blocking issue stopped generation or repair. |
-| `/repair-feedback` | A rejected section received model-readable repair hints. |
-| `/repair-summary` | Counts of queued, cancelled, repaired, and failed repairs. |
+| `/validation-blocked` | A blocking issue stopped generation or validation retry. |
+| `/repair-feedback` | A rejected section received model-readable retry hints. |
+| `/repair-summary` | Counts of queued, cancelled, retried, and failed repairs. |
| `/stream-graph-summary` | Final `StreamGraph.snapshot()` for the server stream. |
| `/protocol-skip` | A non-fatal line was skipped before reaching the sandbox. |
| `/screen-synthesized` | The server synthesized screen structure from sections. |
| `/mode-upgraded` | The server upgraded static generation to interactive mode. |
| `/error` | Server-side generation error or blocked-generation message. |
-Open the **Stream** drawer on `/generate.html` to inspect these lines as they
-arrive.
-
## Devtools Events
The generate demo records a per-run `EventStore`. Open the **Devtools** drawer
@@ -53,20 +162,20 @@ and look for:
- `protocol-parse-error` - raw model output that was not valid JSONL.
- `sandbox-ready` - the iframe booted and can receive state or renders.
- `render` - accepted HTML was sent to the sandbox.
-- `intent-emitted` - generated UI emitted an allowed bridge message.
-- `intent-rejected` - generated UI tried an unknown or malformed intent.
+- `intent-emitted` - generated UI emitted an allowed host tool request.
+- `intent-rejected` - generated UI tried an unknown or malformed request.
- `intent-dispatched` / `intent-settled` - `PolicyEngine` ran a host handler.
- `state-pushed` - host state changed and was pushed back to the sandbox.
- `component-sync` - the sandbox reported the current component placeholders
with measured bounds. The sandbox resyncs after render, state binding,
foreach stamping, iframe scroll, nested scroll, resize, and observed
placeholder size changes.
-- `component-error` - the host rejected or unmounted a component island because
+- `component-error` - the host rejected or unmounted a component overlay because
the name, props, bounds, or registry compatibility failed. The event includes
a stable code such as `bounds-invalid`, `unknown-component`, `props-invalid`,
or `registry-missing`.
-- `surface-plan` - host-owned purpose/runtime/data/authority/persistence plan.
-- `stream-graph` - client-side section health from `StreamGraph.snapshot()`.
+- `surface-plan` - host-owned compiled safety plan.
+- `stream-graph` - client-side stream diagnostics from `StreamGraph.snapshot()`.
- `sandbox-fatal` - bootstrap detected an unsafe sandbox configuration.
Healthy interactive runs usually show `surface-plan`, `protocol-line`, `render`,
@@ -90,37 +199,7 @@ interface ContractIssue {
```
Use `hintsForContractIssue(issue)` when presenting issues back to a model or an
-agent. Common fixes:
-
-- `external-url` - inline assets as data URLs or remove the reference.
-- `unsafe-tag` - remove iframe, object, embed, link, meta, or base-like tags.
-- `inline-handler` - use `data-summon-on-*` or scoped `addEventListener`.
-- `static-script` - remove scripts or switch to interactive mode.
-- `script-not-granted` - use only declarative `data-summon-*` bindings, or
- select `SurfacePolicy.tier: "scripted"` for a scripted host tier.
-- `surface-policy-*` - fix the host-selected `SurfacePolicy`; the compiler
- blocks unknown grants/components and tier-exceeded authority before the model
- is called.
-- `unknown-intent` - use only capabilities granted in the Capabilities block.
-- `invalid-args-json` - make `data-summon-args` a valid one-line JSON object.
-- `unknown-component` - use only names from the Components prompt block.
-- `component-missing-name` - remove stray component id/props attributes or add
- `data-summon-component`.
-- `component-id-missing` / `component-id-invalid` / `component-id-duplicate` -
- give every placeholder one stable, unique id such as `revenue-card`.
-- `component-props-missing` / `component-props-invalid` - make
- `data-summon-props` a valid one-line JSON object.
-- `nested-component` - keep component placeholders as siblings in the freeform
- layout; do not put one placeholder inside another.
-- `surface-runtime-exceeded` - use only capabilities allowed by the compiled
- SurfacePlan runtime.
-- `surface-data-exceeded` - align resource/worker usage with the selected
- SurfacePlan data source.
-- `surface-authority-exceeded` - remove the action or select a plan/grant that
- carries the needed authority, such as `approval-gated`.
-- `resource-loading-not-rendered` - render a visible loading binding.
-- `resource-error-not-rendered` - render a visible error binding.
-- `resource-data-not-rendered` - render a visible data binding or foreach.
+agent.
## Reading StreamGraph
@@ -134,61 +213,7 @@ Healthy sections are both declared and present. Watch these health counters:
- `undeclaredPresent` - the model supplied a section not declared in `/screen`.
- `skippedCount` - lines were skipped by the hardener.
- `blockedCount` - blocking validation issues were recorded.
-- `repairedCount` - sections were accepted after repair feedback.
+- `repairedCount` - sections were accepted after validation retry feedback.
Server streams end with `/stream-graph-summary`. The demo client also emits
live `stream-graph` events after section updates and final render.
-
-## Debugging Loops
-
-When a generated UI fails to render:
-
-1. Check the Stream drawer for `/error`, `/validation-blocked`, and
- `/validation-summary`.
-2. Check Devtools for `protocol-parse-error` and `render`.
-3. Check `/stream-graph-summary` for missing or blocked sections.
-4. Fix the prompt contract, direction, layout, or repair hints before changing
- sandbox runtime code.
-
-When a generated control does not work:
-
-1. Confirm the page is in interactive mode.
-2. Confirm the capability exists in `createCapabilityRegistry(...).toContract()`.
-3. Confirm the generated markup uses a granted trigger and valid
- `data-summon-args`.
-4. Check Devtools for `intent-rejected`, `intent-dispatched`,
- `intent-settled`, and `state-pushed`.
-5. Check the host handler in `PolicyEngine` and the resource's `stateKeys`.
-
-When a resource UI looks empty:
-
-1. Confirm `defineDataResource` has `defaultData` that matches `resultSchema`.
-2. Confirm `stateKeys.loading`, `stateKeys.data`, and `stateKeys.error` are all
- present.
-3. Confirm generated markup includes visible loading, error, and data bindings.
-4. Trigger the resource and inspect `state-pushed` for the resource state patch.
-
-When a component island does not appear:
-
-1. Confirm the host registered the component and passed
- `componentRegistry.toContract().pack` into generation.
-2. Confirm the sandbox artifact or replay envelope includes compatible
- `grants.components`.
-3. Check the Stream drawer for `unknown-component`,
- `component-props-invalid`, `nested-component`, and surface-plan issues.
-4. Check Devtools for `component-sync` followed by `component-error`.
-5. Use the `component-error` code to narrow the fix: `bounds-invalid` means the
- placeholder has empty/offscreen/oversized bounds, `props-invalid` means Zod
- rejected the props, and `registry-missing` means replay has component grants
- but the host did not provide a compatible registry.
-6. Confirm host-side Zod validation accepts the props before looking at the
- component renderer.
-
-When sandbox safety looks suspect:
-
-1. Run `pnpm test:safety`.
-2. If it fails, inspect the Playwright trace/screenshot.
-3. For manual inspection, run `pnpm dev:all` and open
- `http://localhost:5173/adversarial.html`.
-4. Confirm network, storage, parent DOM, and ungranted intent checks still pass.
-5. Inspect `spawnSandbox` before changing iframe sandbox attributes or CSP.
diff --git a/docs/adoption/integration.md b/docs/adoption/integration.md
index 0def953..d0746bf 100644
--- a/docs/adoption/integration.md
+++ b/docs/adoption/integration.md
@@ -1,12 +1,23 @@
# Summon Integration Guide
-Use this when wiring Summon into a host app or server. The goal is to reuse the
-current contract path and package-owned generation lifecycle.
+Use this when wiring Summon into a host app or server. The product model is:
-## 1. Define Host Capabilities
+1. Register host tools.
+2. Register trusted host components.
+3. Choose a surface config.
+4. Generate the surface.
+5. Render it in the sandbox.
+6. Inspect diagnostics when needed.
-Capabilities are host-owned. The model receives the contract, but only the host
-gets handlers, credentials, network, and durable state.
+The TypeScript APIs still use precise runtime names such as capability,
+`SurfacePolicy`, and `PolicyEngine`. In adopter-facing prose, think of them as
+host tools, surface config, and host dispatch.
+
+## 1. Register Host Tools
+
+Host tools are data sources or actions the generated UI may request. The host
+owns handlers, credentials, network, validation, and durable state. The model
+receives only a description of the tool.
```ts
import { z } from 'zod';
@@ -58,11 +69,11 @@ const capabilityContract = registry.toContract();
`capabilityContract.pack` is model-facing. `capabilityContract.validationCapabilities`
and `capabilityContract.initialState` are runtime-facing.
-## 2. Define Component Islands
+## 2. Register Trusted Host Components
-Component islands are also host-owned. The model receives names, descriptions,
-prop schemas, examples, sizing hints, and placeholder rules. It never receives
-component implementations.
+Trusted host components let the generated UI place a host-rendered component
+without receiving its implementation. The model receives names, descriptions,
+prop schemas, examples, sizing hints, and placeholder rules.
```ts
import { z } from 'zod';
@@ -100,17 +111,12 @@ is runtime-facing. The default component surface is
`host-action` only when the trusted host component actually reads host data or
emits host actions.
-## 3. Run Server Generation
+## 3. Choose A Surface Config
-The generation server should use `@anarchitecture/summon-server` for the repeatable lifecycle:
-compile contracts, emit host-owned meta lines, harden model JSONL, optionally
-repair retryable sections, and end with validation and stream-graph summaries.
+A surface config is the host's per-run choice of what the generated UI is
+allowed to do. The API type is `SurfacePolicy`.
```ts
-import {
- runSurfaceGeneration,
- type SummonModelProvider,
-} from '@anarchitecture/summon-server';
import type { SurfacePolicy } from '@anarchitecture/summon';
const surfacePolicy: SurfacePolicy = {
@@ -118,6 +124,31 @@ const surfacePolicy: SurfacePolicy = {
purpose: 'explore',
grants: ['search'],
};
+```
+
+Common configs:
+
+| Situation | Surface config |
+| --- | --- |
+| Read-only summary | `{ tier: "static", purpose: "inform" }` |
+| Host-backed search | `{ tier: "declarative", purpose: "explore", grants: ["search"] }` |
+| Background host work | `{ tier: "worker", purpose: "review", grants: ["analysis"] }` |
+| Requires approval | `{ tier: "approval", purpose: "operate", grants: ["publish_summary"] }` |
+
+Hosts choose the config before generation. The model may react to the compiled
+safety details, but it cannot widen what the host allowed.
+
+## 4. Generate The Surface
+
+The generation server should use `@anarchitecture/summon-server` for the
+repeatable lifecycle: assemble prompts, apply the surface config, validate
+streamed JSONL, optionally retry invalid sections, and emit diagnostics.
+
+```ts
+import {
+ runSurfaceGeneration,
+ type SummonModelProvider,
+} from '@anarchitecture/summon-server';
const modelProvider: SummonModelProvider = async function* ({ prompt, promptBlocks }) {
// Convert promptBlocks into your provider's system-message shape, then yield
@@ -131,8 +162,8 @@ await runSurfaceGeneration({
surfacePolicy,
direction,
layout,
- // Full host ceilings. Summon narrows these from surfacePolicy before
- // constructing prompt and validation contracts.
+ // Full host tool/component catalog. Summon narrows it from the surface config
+ // before constructing model-facing and validation contracts.
capabilities: capabilityContract.pack,
components: componentContract.pack,
activeTokensCss: direction?.tokensCss ?? null,
@@ -144,75 +175,21 @@ await runSurfaceGeneration({
});
```
-Surface policies are host-owned. A model may react to the compiled plan, but it
-must not emit or widen `/surface-policy` or `/surface-plan`;
-`runSurfaceGeneration()` emits both meta lines before model output for clients
-and replay envelopes. Hosts choose the policy before generation.
-
-Common policies:
-
-| Situation | SurfacePolicy |
-| --- | --- |
-| Static summary | `{ tier: "static", purpose: "inform" }` |
-| Host-backed search | `{ tier: "declarative", purpose: "explore", grants: ["search"] }` |
-| Worker-backed analysis | `{ tier: "worker", purpose: "review", grants: ["analysis"] }` |
-| Approval-gated operation | `{ tier: "approval", purpose: "operate", grants: ["publish_summary"] }` |
-
-To enable targeted repair, pass `repair: { enabled: true, provider, maxAttempts,
-maxTargets }`. The repair provider receives the compiled prompt blocks and a
-single replacement prompt; return one replacement JSONL line for the same
-section path.
+To enable validation retries, pass
+`repair: { enabled: true, provider, maxAttempts, maxTargets }`. The provider
+receives the compiled prompt blocks and a single replacement prompt; return one
+replacement JSONL line for the same section path.
-## 4. Apply Protocol On The Client
+## 5. Render In The Sandbox
-The client should let `@anarchitecture/summon` own chunk decoding, protocol parsing,
-section accumulation, stream health, and render timing. Product hosts still own
+The client should let `@anarchitecture/summon` own chunk decoding, protocol
+parsing, stream diagnostics, and render timing. Product hosts still own
fetching, aborts, request payloads, and product-specific meta interpretation.
```ts
import { compileSurfacePolicy } from '@anarchitecture/summon';
-import { consumeSurfaceStream } from '@anarchitecture/summon/browser';
-
-const compiledPolicy = compileSurfacePolicy(surfacePolicy, {
- capabilities: capabilityContract.pack,
- components: componentContract.pack,
-});
-const response = await fetch('/api/generate', {
- method: 'POST',
- body: JSON.stringify({
- prompt,
- surfacePolicy,
- capabilities: capabilityContract.pack,
- components: componentContract.pack,
- }),
-});
-
-const result = await consumeSurfaceStream(response.body!, {
- mode: compiledPolicy.mode,
- onMeta: (line) => {
- if (line.path === '/status') renderStatus(String(line.value));
- },
- onGraph: (snapshot) => {
- events.push({ kind: 'stream-graph', at: Date.now(), health: snapshot.health });
- },
- onRenderHtml: (html) => {
- sandbox?.render(html);
- },
-});
-```
-
-Static streams render as accepted structural lines change. Interactive streams
-render once at completion so scripts execute against a complete DOM. Devtools
-consumers can publish `stream-graph` events from the snapshots so engineers can
-inspect section health without reading raw JSONL.
-
-## 5. Spawn The Sandbox
-
-The sandbox is the only place generated HTML runs. Grants come from the host,
-not from the artifact.
-
-```ts
import {
+ consumeSurfaceStream,
createComponentIslandRegistry,
spawnSandbox,
type SandboxHandle,
@@ -223,31 +200,35 @@ import {
tokensSource,
} from '@anarchitecture/summon/assets';
-let sandbox: SandboxHandle | null = null;
-const islands = createComponentIslandRegistry({
- outerIframe: iframe,
- registry: componentRegistry,
+const compiledPolicy = compileSurfacePolicy(surfacePolicy, {
+ capabilities: capabilityContract.pack,
+ components: componentContract.pack,
});
+let sandbox: SandboxHandle | null = null;
+const grantedCapabilities = capabilityContract.validationCapabilities;
const policy = new PolicyEngine({
initialState: capabilityContract.initialState,
handlers: registry.toPolicyHandlers(),
- onStateChange: (state) => {
- sandbox?.pushState(state);
- },
+ onStateChange: (state) => sandbox?.pushState(state),
+});
+
+const islands = createComponentIslandRegistry({
+ outerIframe: iframe,
+ registry: componentRegistry,
});
sandbox = spawnSandbox({
iframe,
artifact: {
+ html: '',
intents: policy.intents,
- capabilities: capabilityContract.validationCapabilities,
+ capabilities: grantedCapabilities,
components: componentContract.validationComponents,
- html: '',
initialState: policy.getState(),
},
grantedIntents: policy.intents,
- grantedCapabilities: capabilityContract.validationCapabilities,
+ grantedCapabilities,
bootstrapSource,
tokensSource,
onIntent: (intent, args) => {
@@ -262,61 +243,72 @@ sandbox = spawnSandbox({
});
},
});
-```
-
-This preserves the core invariant: the iframe may emit only host-granted intent
-names, and handlers run only after schema validation inside `PolicyEngine`.
-For LLM-authored artifacts, always pass `grantedIntents` and
-`grantedCapabilities` from host-owned contracts. `artifact.intents` and
-`artifact.capabilities` describe what the artifact claims to use; they are not
-permission.
+const response = await fetch('/api/generate', {
+ method: 'POST',
+ body: JSON.stringify({
+ prompt,
+ surfacePolicy,
+ capabilities: capabilityContract.pack,
+ components: componentContract.pack,
+ }),
+});
-Component placeholders stay inside the sandbox HTML, but trusted component DOM is
-rendered by the host overlay. The sandbox only sends `SUMMON_COMPONENTS` bounds
-and props with its `sandbox_id`; it cannot inspect the host-rendered island DOM.
+await consumeSurfaceStream(response.body!, {
+ mode: compiledPolicy.mode,
+ onMeta: (line) => {
+ if (line.path === '/status') renderStatus(String(line.value));
+ },
+ onGraph: (snapshot) => {
+ events.push({ kind: 'stream-graph', at: Date.now(), health: snapshot.health });
+ },
+ onRenderHtml: (html) => {
+ sandbox?.render(html);
+ },
+});
+```
-## 6. Resource Markup The Model Should Emit
+This preserves the main invariant: the sandbox may request only host-allowed
+tool names, and handlers run only after schema validation in the host.
-Data resources use declarative bindings. A generated search form should look
-like this shape:
+Generated data-resource UI should use safe `data-summon-*` bindings instead of
+inline handlers:
```html
-
-
-
- Searching...
-
-
-
-
-
-
-
+
```
-Use `data-summon-*` bindings instead of inline handlers. External URLs, unsafe
-tags, ungranted intents, and missing resource states are contract issues.
-
-Component placeholders follow the same declarative pattern:
+Trusted component placeholders follow the same declarative pattern:
```html
```
-Use placeholders only when a registered component materially improves fidelity.
-Freeform HTML and CSS remain the primary composition layer.
+## 6. Inspect Diagnostics
+
+Diagnostics are for failures and maintainer investigation, not the first thing
+an adopter needs to learn.
+
+- If generation fails, inspect `/error`, `/validation-summary`,
+ `/validation-blocked`, and validation retry feedback in the Stream drawer.
+- If a generated control does nothing, inspect Devtools for rejected host tool
+ requests, host dispatch, handler completion, and pushed state.
+- If trusted components do not appear, inspect component sync and component
+ error events.
+- If sandbox safety looks suspect, run `pnpm test:safety` and inspect
+ `spawnSandbox` before changing iframe sandbox attributes or CSP.
diff --git a/docs/adoption/mobile-webviews.md b/docs/adoption/mobile-webviews.md
index 16c8e32..d40e85a 100644
--- a/docs/adoption/mobile-webviews.md
+++ b/docs/adoption/mobile-webviews.md
@@ -1,15 +1,17 @@
# Mobile WebView Requirements
Summon is web-first. Native iOS or Android wrappers are not part of V1, but any
-WebView host must keep the same security shape as browser/Tauri hosts.
+WebView host must preserve the same shape: generated UI runs in a locked inner
+surface, and native privileges stay with the host.
-- Generated content must never receive a native bridge object.
-- Generated content must run inside a sandboxed inner frame when the WebView
- supports iframe sandboxing.
+- Generated UI must never receive a native bridge object.
+- Generated UI must run inside a sandboxed inner frame when the WebView supports
+ iframe sandboxing.
- The outer native WebView owns credentials, network, durable state, and native
- APIs. It may pass safe state into Summon, but Summon artifacts cannot call
- native APIs directly.
+ APIs. It may pass safe state into Summon, but generated UI cannot call native
+ APIs directly.
- If the host cannot prove an opaque/sandboxed inner boundary, degrade to
- static or declarative rendering with no scripts and no executable grants.
+ read-only or declarative rendering with no scripts and no executable host
+ tools.
- Treat WebKit safety tests as the feasible V1 proxy for WebView behavior, then
add native wrapper tests before enabling privileged mobile bridges.
diff --git a/docs/adoption/package-consumption.md b/docs/adoption/package-consumption.md
index ed70a6c..66cb405 100644
--- a/docs/adoption/package-consumption.md
+++ b/docs/adoption/package-consumption.md
@@ -6,14 +6,24 @@ or `@summon-internal/*` packages from applications.
For package boundary rationale, see
[Public Packaging Plan](public-packaging.md).
-The root `@anarchitecture/summon` entrypoint is intentionally curated for
-host-authoring helpers, component/capability registries, policy helpers, and
-surface-plan types. Use explicit subpaths for runtime and advanced APIs:
-
-- `@anarchitecture/summon/browser` for iframe spawning, stream consumption,
- component islands, and strict input.
-- `@anarchitecture/summon/engine` for protocol parsing, validators, prompt
- contracts, `SectionAccumulator`, `StreamGraph`, and hardening.
+Use the public packages by install environment:
+
+```txt
+@anarchitecture/summon
+@anarchitecture/summon-server
+@anarchitecture/summon-react
+```
+
+The root `@anarchitecture/summon` entrypoint is curated for host-authoring:
+registering host tools, registering trusted host components, choosing surface
+configs, and dispatching host-owned requests. Use explicit subpaths when you
+need lower-level browser, engine, host, policy, envelope, assets, or Devtools
+APIs:
+
+- `@anarchitecture/summon/browser` for sandbox spawning, stream consumption,
+ trusted component overlays, and strict input.
+- `@anarchitecture/summon/engine` for advanced protocol, validation, prompt
+ contract, stream diagnostic, and hardening APIs.
- `@anarchitecture/summon/host` for adapter authors who need the full host
runtime surface.
@@ -25,13 +35,12 @@ import { createCapabilityRegistry, defineAction } from '@anarchitecture/summon';
import { tokensSource } from '@anarchitecture/summon/assets';
```
-`SummonSurface` accepts an envelope or direct `html` / `protocolLines`. Pass a
-host-owned `capabilityRegistry`; artifact-declared grants are advisory and are
-never executable permission.
-React component islands require the host app to provide `react-dom` as a peer
-dependency.
+`SummonSurface` accepts a replay envelope or direct `html` / `protocolLines`.
+Pass a host-owned `capabilityRegistry`; generated declarations are advisory and
+are never executable permission. Trusted host component overlays require the
+host app to provide `react-dom` as a peer dependency.
-React hosts can register component islands with host-owned React components:
+React hosts can register trusted host components:
```tsx
import { z } from 'zod';
@@ -58,10 +67,10 @@ const componentRegistry = createComponentRegistry([
```
Pass `componentRegistry.toContract().pack` to generation when requesting the
-surface. The React component renders in host DOM as an overlay island, not
-inside the sandbox iframe.
+surface. The React component renders in host DOM as an overlay, not inside the
+sandbox iframe.
-When a React component needs to call a host-granted intent, map the runtime
+When a React component needs to request a host-owned action, map the runtime
context into explicit component props:
```tsx
@@ -82,6 +91,8 @@ defineReactComponent({
```ts
import {
compileSurfacePolicy,
+ createComponentRegistry,
+ defineComponent,
} from '@anarchitecture/summon';
import {
consumeSurfaceStream,
@@ -89,10 +100,6 @@ import {
spawnSandbox,
type SandboxHandle,
} from '@anarchitecture/summon/browser';
-import {
- createComponentRegistry,
- defineComponent,
-} from '@anarchitecture/summon';
import { PolicyEngine } from '@anarchitecture/summon/policy';
import {
bootstrapSource,
@@ -101,18 +108,15 @@ import {
```
Use `consumeSurfaceStream()` to decode streamed chunks, parse accepted protocol
-lines, maintain section HTML and stream graph health, and render through the
-sandbox handle. Spawn the iframe with `grantedIntents` and
-`grantedCapabilities` from host-owned contracts.
-`compileSurfacePolicy(surfacePolicy, ceilings)` gives the client the stream
+lines, maintain generated HTML, update stream diagnostics, and render through
+the sandbox handle. Spawn the iframe with allowed host tools from host-owned
+contracts.
+
+`compileSurfacePolicy(surfacePolicy, catalogs)` gives the client the stream
mode and narrowed contracts that the server will enforce. Generation authority
-comes from the explicit `surfacePolicy` the host submits.
+comes from the explicit surface config the host submits.
```ts
-const compiledPolicy = compileSurfacePolicy(surfacePolicy, {
- capabilities: capabilityContract.pack,
- components: componentContract.pack,
-});
const componentRegistry = createComponentRegistry([
defineComponent({
name: 'MetricCard',
@@ -123,7 +127,13 @@ const componentRegistry = createComponentRegistry([
},
}),
]);
+
const componentContract = componentRegistry.toContract();
+const compiledPolicy = compileSurfacePolicy(surfacePolicy, {
+ capabilities: capabilityContract.pack,
+ components: componentContract.pack,
+});
+const grantedCapabilities = capabilityContract.validationCapabilities;
let handle: SandboxHandle | null = null;
const islands = createComponentIslandRegistry({
@@ -184,10 +194,9 @@ import {
```
`runSurfaceGeneration()` is provider-neutral. The provider receives compiled
-prompt blocks and returns text chunks. The runner compiles contracts, emits
-host-owned meta lines such as `/surface-policy` and `/surface-plan`, validates JSONL, optionally runs
-targeted repair, emits accepted Summon lines and diagnostics, and returns a
-replay summary.
+prompt blocks and returns text chunks. The runner applies the surface config,
+validates streamed JSONL, optionally runs targeted validation retries, emits
+accepted Summon lines and diagnostics, and returns a replay summary.
`generateSurfaceStream()` remains available for existing integrations that
consume an async generator, but new servers should prefer
diff --git a/docs/adoption/public-packaging.md b/docs/adoption/public-packaging.md
index 40c0595..d34a0af 100644
--- a/docs/adoption/public-packaging.md
+++ b/docs/adoption/public-packaging.md
@@ -15,10 +15,9 @@ Publish by install environment, not by internal implementation layer.
```
`@anarchitecture/summon` is the frameworkless client/core package. Its root
-entrypoint is curated for host-authoring helpers: capability and component
-registries, `PolicyEngine`, and `SurfacePolicy` helpers/types. Compiled
-`SurfacePlan` helpers and advanced runtime surfaces live behind explicit
-subpaths:
+entrypoint is curated for host-authoring helpers: host tool and component
+registries, `PolicyEngine`, and `SurfacePolicy` helpers/types. Advanced runtime
+helpers, including compiled `SurfacePlan` APIs, live behind explicit subpaths:
```txt
@anarchitecture/summon/browser
@@ -30,19 +29,19 @@ subpaths:
@anarchitecture/summon/devtools
```
-Use `/browser` for iframe spawning, stream consumption, component islands, and
-strict input. Use `/engine` for protocol, validation, prompt contracts, stream
-graph, and hardening. Use `/host` only when writing adapters that need the full
-host runtime surface.
+Use `/browser` for sandbox spawning, stream consumption, trusted component
+overlays, and strict input. Use `/engine` for protocol, validation, prompt
+contracts, stream diagnostics, and hardening. Use `/host` only when writing
+adapters that need the full host runtime surface.
`@anarchitecture/summon-server` is the provider-neutral generation package. It
-owns `runSurfaceGeneration`, prompt/contract assembly, repair feedback, summary
-helpers, and model-provider interfaces. It may depend on the core package but
-should not pull in browser or React peers.
+owns `runSurfaceGeneration`, prompt/contract assembly, validation retry
+feedback, summary helpers, and model-provider interfaces. It may depend on the
+core package but should not pull in browser or React peers.
`@anarchitecture/summon-react` is the React adapter. It owns `SummonSurface`,
-`defineReactComponent`, and React component island lifecycle. It depends on the
-core package and has `react` / `react-dom` as peer dependencies.
+`defineReactComponent`, and trusted component overlay lifecycle. It depends on
+the core package and has `react` / `react-dom` as peer dependencies.
Future adapters should follow the same rule:
diff --git a/docs/adoption/quickstart.md b/docs/adoption/quickstart.md
index 9911db9..4e0112c 100644
--- a/docs/adoption/quickstart.md
+++ b/docs/adoption/quickstart.md
@@ -1,9 +1,8 @@
# Summon Adoption Quickstart
This is the golden path for proving Summon works locally. Start with the Surface
-Gallery to see rich host-owned surfaces without workbench controls, then use the
-Workbench to inspect generation, interactive data resources, host state
-pushback, Devtools events, stream health, and sandbox boundaries.
+Gallery to see generated UI in a sandbox, backed only by host tools the app
+allows. Use the maintainer workbench only when you want to inspect diagnostics.
## Prerequisites
@@ -24,12 +23,12 @@ Open `http://localhost:5174`.
The gallery is live-first. It requires `apps/server` and `ANTHROPIC_API_KEY`;
it does not silently fall back to replay. Use the preset cards to generate
-static, host-resource, host-action, approval-gated, component-island, and
-worker-backed surfaces.
+read-only surfaces, host-backed search, host-owned actions, approval flows,
+trusted host components, and background host work.
-Each preset sends an explicit `SurfacePolicy` plus capability/component
-ceilings to `/api/generate`. The server compiles that policy into narrowed
-contracts, matching script policy, and the diagnostic `/surface-plan` event.
+Each preset chooses a surface config and a short list of allowed host tools.
+The server turns that into the stricter validation details Summon uses during
+generation and replay.
## Run The Workbench
@@ -41,50 +40,55 @@ Open `http://localhost:5173/generate.html`.
## Golden Scenario
-In the workbench, use the **Host-resource search** scenario. The scenario is
-intentionally shaped to exercise the adoption path:
+In the workbench, use the **Host Data Search** scenario. The scenario is
+shaped to exercise the adopter path:
-- `defineDataResource` via the demo `search` resource.
-- Loading, error, and data states through resource bindings.
-- A narrowed model-facing capability pack and matching sandbox grants.
-- Host state pushback from `PolicyEngine`.
-- A server-emitted `SurfacePolicy` plus compiled `SurfacePlan`.
-- Devtools `stream-graph` health events.
+- The host registers a `search` data tool with `defineDataResource`.
+- The generated surface renders loading, error, and result states.
+- The surface can only request the `search` host tool.
+- The host owns state updates and pushes safe state back into the sandbox.
+- Diagnostics are available if generation or interaction fails.
## What To Verify
-1. Select **Host-resource search**.
+1. Select **Host Data Search**.
2. Keep layout on **Free layout**.
-3. Confirm the contract cockpit shows
- `explore/declarative/host-resource/read/replayable` and `Grants 1: search`.
+3. Confirm the run is interactive and only the `search` host tool is allowed.
4. Run the scenario.
5. When the UI renders, use its generated search control with a query such as
`chicken pasta`.
-6. Open the **Stream** drawer and confirm accepted `add` or `set` protocol
- lines plus `/surface-policy` and `/surface-plan` are visible.
-7. Open the **Devtools** drawer and confirm these event kinds appear:
- `protocol-line`, `intent-emitted`, `intent-dispatched`, `state-pushed`,
- `render`, `surface-plan`, and `stream-graph`.
-8. Confirm the `stream-graph` events report declared and present sections
- without blocked sections.
-9. Open **Saved surfaces** and replay the completed surface. It should render
- from the stored `SurfaceEnvelope` while keeping the sandbox boundary intact.
+6. Confirm the generated UI displays loading and then search results.
+7. Open **Saved surfaces** and replay the completed surface. It should render
+ the same UI while keeping the sandbox boundary intact.
Then open `http://localhost:5173/adversarial.html` and confirm the sandbox
checks pass. This proves the quickstart did not require relaxing the sandbox
boundary.
+## Optional Diagnostics
+
+The Stream and Devtools drawers are for understanding a run after you have
+rendered and interacted with a surface:
+
+- Open the **Stream** drawer to inspect accepted protocol lines, the selected
+ surface config, validation summaries, and validation retry feedback.
+- Open the **Devtools** drawer to inspect sandbox startup, render events, host
+ tool requests, host dispatch, pushed state, trusted component sync, and stream
+ diagnostics.
+- For a healthy interactive run, expect to see a render event, a host tool
+ request when you submit the search, host dispatch, and pushed state.
+
## Optional Checks
Open `http://localhost:5173/batch.html` to run several prompts through the same
-direction and capability ceiling. Use it when changing prompt contracts,
-directions, intent wiring, visual direction coverage, or throughput behavior.
+surface config and allowed host tool set. Use it when changing prompt contracts,
+directions, host tool wiring, visual direction coverage, or throughput behavior.
Use the other `/generate.html` scenarios to exercise static summaries,
-declarative forms, host AI calls, GitHub lookup, component islands,
-worker-backed analysis, approval-gated publish, scripted interactive mode,
+declarative forms, host AI calls, GitHub lookup, trusted host components,
+background host work, approval-required publish, scripted interactive mode,
token overrides, layout constraints, sibling summon, Ghost steering when
-configured, and repair diagnostics.
+configured, and validation retry diagnostics.
Open `http://localhost:5173/strict.html` to see the trusted host overlay pattern
for sensitive input. The generated sandbox describes the slot; the host owns the
@@ -94,11 +98,12 @@ real input and pushes only safe state back.
- If generation fails immediately, check `apps/server/.env` for
`ANTHROPIC_API_KEY` and confirm the server is listening on `:3001`.
-- If generated controls do nothing, confirm the page is in **Interactive** mode.
- Static mode intentionally has no granted intents.
-- If the model emits unsafe HTML, inspect `/validation-summary`,
- `/repair-feedback`, and `/repair-summary` in the Stream drawer.
-- If the sandbox does not update after an intent, inspect Devtools for
- `intent-rejected`, `intent-dispatched`, `intent-settled`, and `state-pushed`.
-- If sections are missing or repaired, inspect `/stream-graph-summary` and the
- Devtools `stream-graph` events.
+- If generated controls do nothing, confirm the run is interactive. Static
+ surfaces intentionally have no allowed host tools.
+- If the model emits unsafe HTML, inspect the Stream drawer for validation
+ summaries, blocked output, and validation retry feedback.
+- If the sandbox does not update after a generated control is used, inspect
+ Devtools for rejected host tool requests, host dispatch, handler completion,
+ and pushed state.
+- If sections are missing or retried, inspect stream diagnostics in the Stream
+ and Devtools drawers.
diff --git a/docs/adoption/security.md b/docs/adoption/security.md
index a3ae01a..4c41803 100644
--- a/docs/adoption/security.md
+++ b/docs/adoption/security.md
@@ -1,56 +1,66 @@
# Summon Security Posture
-Summon is production-oriented because generated UI runs behind a host-owned
-boundary. The model can propose HTML, CSS, and intent declarations, but it does
-not receive network, credentials, durable storage, parent DOM access, or handler
-execution.
+Summon's security invariant is simple: generated UI runs in a locked iframe and
+can only request host tools the host allowed for that run. The host owns network,
+credentials, durable state, native APIs, handlers, and persistence.
+
+The model may propose HTML, CSS, and requests to use host tools. It does not get
+ambient access to the parent app, and it cannot give itself new authority.
## Security Boundary
-The hard boundary is:
+The hard boundary is the browser sandbox:
- `spawnSandbox()` creates a null-origin iframe with `sandbox="allow-scripts"`.
- The sandbox CSP blocks network, external assets, forms, frames, workers,
object/embed content, and storage-backed same-origin access.
- The bridge accepts only messages carrying the per-sandbox random
`sandbox_id`.
-- `grantedIntents` and `grantedCapabilities` come from the host. Artifact
- declarations are advisory, and missing `grantedIntents` grants nothing.
-- `PolicyEngine` validates intent args before host handlers run.
+- Host-owned allowlists (`grantedIntents` and `grantedCapabilities`) decide
+ which generated requests can run.
+- `PolicyEngine` validates request args before host handlers run.
- Data resources fetch through host-owned handlers and validate returned data
before pushing state back.
-- Component islands render trusted host DOM outside the iframe after the host
- validates registered component names and props.
+- Trusted host components render outside the iframe after the host validates
+ registered component names and props.
-The validator is not the security perimeter. It is a contract gate and repair
-guide that rejects or warns on unsafe tags, external URLs, inline handlers, bad
-args, unknown intents, missing resource states, token drift, and layout
-violations before HTML reaches the iframe. If a validator misses a weird HTML
-shape, the iframe/CSP/bridge should still contain it.
+The validator is not the security perimeter. It is a contract gate and
+diagnostic guide that rejects or warns on unsafe tags, external URLs, inline
+handlers, bad args, unknown host tool requests, missing resource states, token
+drift, and layout violations before HTML reaches the iframe. If a validator
+misses a weird HTML shape, the iframe/CSP/bridge should still contain it.
-## Production Tiers
+## Surface Types
-Use the narrowest tier that fits the host surface.
+Use the narrowest surface type that fits the product experience. The API field
+for this choice is `SurfacePolicy.tier`.
-| Tier | Contract | When to use |
+| Surface type | API setting | When to use |
| --- | --- | --- |
-| Static | `SurfacePolicy.tier: "static"` | Read-only summaries, cards, explainers, comparisons, and dashboards. Scripts and capabilities are omitted. |
+| Read-only | `SurfacePolicy.tier: "static"` | Summaries, cards, explainers, comparisons, and dashboards. Scripts and host tools are omitted. |
| Declarative interactive | `SurfacePolicy.tier: "declarative"` | Production default for forms, search, pickers, loading/error/data states, foreach lists, and safe attribute binding. Uses only `data-summon-*`. |
| Scripted interactive | `SurfacePolicy.tier: "scripted"` | Restricted pilots that need custom keyboard handling, DOM-local state, or computed presentation that declarative bindings cannot express. |
-| Worker | `SurfacePolicy.tier: "worker"` | Host-owned background work through worker-backed resources/actions. |
-| Approval | `SurfacePolicy.tier: "approval"` | Operations that require a host approval adapter before the handler runs. |
-
-Declarative interactive still supports clicks, submits, mount-triggered reads,
-data resources, loading/error/data bindings, foreach templates, text binding,
-and safe image/data attributes. It forbids generated `