@konitif/nodal-blockly 0.1.0

package/dist/playback.js

@@ -0,0 +1,97 @@
+/** Differential SVG paint only. No workspace serialization or semantic events. */
+export function createBlocklyPlaybackPresentation(workspace) {
+    const applied = new Map();
+    function present(blocks, label) {
+        const nextIds = new Set(Object.keys(blocks));
+        for (const id of applied.keys())
+            if (!nextIds.has(id)) {
+                const block = workspace.getBlockById(id);
+                if (block) {
+                    const root = block.getSvgRoot();
+                    delete root.dataset.playbackState;
+                    delete root.dataset.playbackWarning;
+                    delete root.dataset.playbackWarningMessage;
+                    root.querySelector(":scope > .konitifBlocklyPlayback")?.remove();
+                    block.setWarningText(null, "konitif-playback");
+                }
+                applied.delete(id);
+            }
+        for (const [id, reading] of Object.entries(blocks)) {
+            const block = workspace.getBlockById(id);
+            if (!block || block.isInsertionMarker() || block.isInFlyout)
+                continue;
+            const root = block.getSvgRoot();
+            const progress = Math.round(Math.min(1, Math.max(0, Number.isFinite(reading.progress) ? reading.progress : 0)) * 100);
+            const caption = label(reading.state);
+            const warning = reading.warning?.message ?? "";
+            // Blockly's public width includes connected statement children. Status
+            // belongs to this block's own header, so anchor it to the childless
+            // outline or a wide nested stack pushes the label into empty canvas.
+            const size = { width: block.width, headerWidth: block.childlessWidth, height: block.height };
+            const signature = JSON.stringify([
+                reading.state,
+                progress,
+                warning,
+                caption,
+                size.width,
+                size.headerWidth,
+                size.height,
+            ]);
+            const previous = applied.get(id);
+            if (previous?.root === root && previous.signature === signature)
+                continue;
+            root.dataset.playbackState = reading.state;
+            if (warning)
+                root.dataset.playbackWarning = "true";
+            else
+                delete root.dataset.playbackWarning;
+            // The vendor owns warning icon placement and tooltip; a scoped ID avoids
+            // clearing unrelated diagnostics. Only a changed warning rerenders it.
+            if (previous?.root !== root ||
+                root.dataset.playbackWarningMessage !== warning) {
+                block.setWarningText(warning || null, "konitif-playback");
+                root.dataset.playbackWarningMessage = warning;
+            }
+            let decoration = root.querySelector(":scope > .konitifBlocklyPlayback");
+            if (!decoration) {
+                decoration = root.ownerDocument.createElementNS("http://www.w3.org/2000/svg", "g");
+                decoration.classList.add("konitifBlocklyPlayback");
+                decoration.setAttribute("pointer-events", "none");
+                decoration.innerHTML =
+                    '<title></title><text text-anchor="end" font-size="8" font-weight="700"></text><line class="konitifBlocklyPlaybackTrack" stroke-width="4" stroke-linecap="round" vector-effect="non-scaling-stroke" /><line class="konitifBlocklyPlaybackValue" stroke-width="2.5" stroke-linecap="round" vector-effect="non-scaling-stroke" />';
+                root.append(decoration);
+            }
+            decoration.querySelector("title").textContent = warning
+                ? `${caption} — ${warning}`
+                : caption;
+            const text = decoration.querySelector("text");
+            text.textContent = caption;
+            text.setAttribute("x", String(Math.max(8, size.headerWidth - 8)));
+            text.setAttribute("y", "11");
+            // A statement stack advances from top to bottom. Project progress in the
+            // same direction, in a quiet gutter outside the block silhouette, rather
+            // than drawing a horizontal meter across the block content.
+            const railX = -8;
+            const railStart = 6;
+            const railEnd = Math.max(railStart, size.height - 6);
+            const track = decoration.querySelector(".konitifBlocklyPlaybackTrack");
+            track.setAttribute("x1", String(railX));
+            track.setAttribute("x2", String(railX));
+            track.setAttribute("y1", String(railStart));
+            track.setAttribute("y2", String(railEnd));
+            const value = decoration.querySelector(".konitifBlocklyPlaybackValue");
+            value.setAttribute("x1", String(railX));
+            value.setAttribute("x2", String(railX));
+            value.setAttribute("y1", String(railStart));
+            value.setAttribute("y2", String(railStart + ((railEnd - railStart) * progress) / 100));
+            value.style.display = progress > 0 ? "" : "none";
+            applied.set(id, { root, signature });
+        }
+    }
+    return {
+        present,
+        reset() {
+            applied.clear();
+        },
+    };
+}

package/dist/projection.d.ts

@@ -0,0 +1,24 @@
+import { type Workflow } from '@konitif/composition';
+import { type NodalDialect } from '@konitif/nodal';
+import type { BlocklyBlockReading, BlocklyNodeContribution, BlocklyProjection, BlocklyWorkflowSnapshot } from './contracts.js';
+/** Presentation eligibility only; shared validation remains the connection authority. */
+export declare function canUseBlocklyValueOutput(definition: NodalDialect['nodeRegistry'][number]): boolean;
+/** A presentation query, not admission. Final edits validate the complete graph. */
+export declare function getBlocklyReferenceChoices(snapshot: BlocklyWorkflowSnapshot, contributions: readonly BlocklyNodeContribution[], occurrences: readonly Pick<BlocklyBlockReading, 'id' | 'contributionId'>[], targetId: string, portId: string): {
+    label: string;
+    reference: {
+        moduleId: string;
+        portId: string;
+    };
+}[];
+/** Tree blocks for simple value dialects; explicit port references for structured dialects. */
+export declare function projectBlocklyWorkflow(snapshot: BlocklyWorkflowSnapshot, contributions: readonly BlocklyNodeContribution[]): BlocklyProjection;
+/** Patch the existing canonical artifact; no whole-workflow roundtrip through a lossy graph encoding. */
+export declare function proposeBlocklyEdit(snapshot: BlocklyWorkflowSnapshot, contributions: readonly BlocklyNodeContribution[], reading: readonly BlocklyBlockReading[]): {
+    accepted: true;
+    candidate: Workflow;
+    changed: boolean;
+} | {
+    accepted: false;
+    reason: string;
+};

package/dist/projection.js

@@ -0,0 +1,275 @@
+import { commitWorkflowComposition } from '@konitif/composition';
+import { createNodeFromDefinition, createNodalGraphDocument, nodalNodeToModule, projectWorkflowToNodalGraph, validateGraphDocument } from '@konitif/nodal';
+const failure = (reason) => ({ accepted: false, reason });
+/** Presentation eligibility only; shared validation remains the connection authority. */
+export function canUseBlocklyValueOutput(definition) {
+    return definition.outputs.length === 1 &&
+        [...definition.inputs, ...definition.outputs].every(port => port.mode === 'value');
+}
+/** A presentation query, not admission. Final edits validate the complete graph. */
+export function getBlocklyReferenceChoices(snapshot, contributions, occurrences, targetId, portId) {
+    const target = occurrences.find(b => b.id === targetId);
+    if (!target)
+        return [];
+    const targetDefinition = resolve(snapshot, contributions, target.contributionId).definition;
+    return occurrences.flatMap(source => {
+        if (source.id === targetId)
+            return [];
+        const definition = resolve(snapshot, contributions, source.contributionId).definition;
+        return definition.outputs.flatMap(port => {
+            const graph = createNodalGraphDocument({ dialect: snapshot.dialect.id });
+            graph.nodes = [source, target].map((occurrence, index) => {
+                const node = createNodeFromDefinition({ definition: index === 0 ? definition : targetDefinition, position: { x: 0, y: 0 } });
+                node.id = occurrence.id;
+                for (const p of [...node.inputs, ...node.outputs])
+                    p.nodeId = node.id;
+                return node;
+            });
+            graph.edges = [{ id: 'projection-query', sourceNodeId: source.id, sourcePortId: port.id, targetNodeId: targetId, targetPortId: portId }];
+            if (!validateGraphDocument(graph, snapshot.dialect).valid)
+                return [];
+            return [{ label: `${port.label} [${port.id}] ← ${definition.title} [${source.id}] (${port.mode}:${port.dataType})`,
+                    reference: { moduleId: source.id, portId: port.id } }];
+        });
+    });
+}
+function resolve(snapshot, contributions, id) {
+    const contribution = contributions.find(c => c.id === id && c.dialectId === snapshot.dialect.id);
+    const definition = snapshot.dialect.nodeRegistry.find(d => d.type === contribution?.nodeType);
+    if (!contribution || !definition)
+        throw new Error(`missing-definition:${id}`);
+    if (contribution.composite)
+        throw new Error(`composite-not-supported:${id}`);
+    const statement = contribution.statement;
+    if (statement) {
+        for (const port of [statement.previous, ...(statement.containers ?? []).map(c => c.portId)].filter(Boolean)) {
+            if (!definition.inputs.some(p => p.id === port))
+                throw new Error(`statement-input-missing:${port}`);
+        }
+        if (statement.next && !definition.outputs.some(p => p.id === statement.next))
+            throw new Error('statement-output-missing');
+    }
+    for (const field of contribution.fields ?? []) {
+        if (!Object.hasOwn(definition.defaultConfig, field.configKey) || typeof definition.defaultConfig[field.configKey] !== (field.editor === 'text' ? 'string' : field.editor)) {
+            throw new Error(`field-not-in-shared-schema:${field.configKey}`);
+        }
+    }
+    return { contribution, definition };
+}
+/** Tree blocks for simple value dialects; explicit port references for structured dialects. */
+export function projectBlocklyWorkflow(snapshot, contributions) {
+    const issues = [];
+    const graph = projectWorkflowToNodalGraph(snapshot.workflow);
+    const blocks = [];
+    const structured = contributions.some(c => {
+        const definition = snapshot.dialect.nodeRegistry.find(d => d.type === c.nodeType && c.dialectId === snapshot.dialect.id);
+        return definition && (definition.outputs.length > 1 || [...definition.inputs, ...definition.outputs].some(p => p.mode !== 'value'));
+    });
+    const hasValues = contributions.some(c => {
+        const definition = snapshot.dialect.nodeRegistry.find(d => d.type === c.nodeType && c.dialectId === snapshot.dialect.id);
+        return definition && canUseBlocklyValueOutput(definition);
+    });
+    const layout = contributions.some(c => c.statement) ? 'mixed' : structured ? (hasValues ? 'mixed' : 'references') : 'tree';
+    if (graph.dialect !== snapshot.dialect.id)
+        issues.push('dialect-mismatch');
+    for (const node of graph.nodes) {
+        try {
+            const contribution = contributions.find(c => c.nodeType === node.type && c.dialectId === snapshot.dialect.id);
+            if (!contribution)
+                throw new Error(`missing-projection:${node.type}`);
+            const { definition } = resolve(snapshot, contributions, contribution.id);
+            if (node.mode !== 'always' || node.locked || node.missingDefinition)
+                throw new Error(`node-state-not-editable:${node.id}`);
+            const module = snapshot.workflow.composition.modules.find(m => m.id === node.id);
+            // Keep unrepresentable contracts intact instead of casting their semantics to a value block.
+            for (const port of module.ports) {
+                const template = (port.direction === 'input' ? definition.inputs : definition.outputs).find(p => p.id === port.id);
+                if (!template || template.mode !== port.contract.mode ||
+                    (port.contract.valueType !== template.dataType && port.contract.valueType !== 'unknown') || port.contract.multiple) {
+                    throw new Error(`port-not-representable:${node.id}:${port.id}`);
+                }
+            }
+            if (module.ports.length !== definition.inputs.length + definition.outputs.length)
+                throw new Error(`schema-changed:${node.id}`);
+            const fields = {};
+            for (const field of contribution.fields ?? []) {
+                const value = node.config[field.configKey] ?? definition.defaultConfig[field.configKey];
+                const expected = field.editor === 'text' ? 'string' : field.editor;
+                if (typeof value !== expected || (typeof value === 'number' && !Number.isFinite(value)))
+                    throw new Error(`field-not-representable:${field.configKey}`);
+                fields[field.configKey] = value;
+            }
+            blocks.push({ id: node.id, contributionId: contribution.id, fields, inputs: Object.fromEntries(definition.inputs.map(p => [p.id, null])) });
+        }
+        catch (error) {
+            issues.push(error instanceof Error ? error.message : 'projection-failed');
+        }
+    }
+    const children = new Set();
+    for (const connection of snapshot.workflow.composition.connections) {
+        const parent = blocks.find(b => b.id === connection.target.moduleId);
+        const child = blocks.find(b => b.id === connection.source.moduleId);
+        const childModule = snapshot.workflow.composition.modules.find(m => m.id === connection.source.moduleId);
+        const outputs = childModule?.ports.filter(p => p.direction === 'output') ?? [];
+        if (!parent || !child || !(connection.target.portId in parent.inputs) || !outputs.some(p => p.id === connection.source.portId) ||
+            (layout === 'tree' && outputs.length !== 1)) {
+            issues.push(`connection-not-representable:${connection.id}`);
+            continue;
+        }
+        if ((layout === 'tree' && children.has(child.id)) || parent.inputs[connection.target.portId] !== null)
+            issues.push(`shared-output-or-occupied-input:${connection.id}`);
+        children.add(child.id);
+        parent.inputs[connection.target.portId] = layout !== 'tree'
+            ? { moduleId: child.id, portId: connection.source.portId } : child.id;
+    }
+    const visiting = new Set(), visited = new Set();
+    const visit = (id) => {
+        if (visiting.has(id)) {
+            issues.push(`cycle-not-supported:${id}`);
+            return;
+        }
+        if (visited.has(id))
+            return;
+        visiting.add(id);
+        for (const child of Object.values(blocks.find(b => b.id === id)?.inputs ?? {}))
+            if (child)
+                visit(typeof child === 'string' ? child : child.moduleId);
+        visiting.delete(id);
+        visited.add(id);
+    };
+    for (const block of blocks)
+        visit(block.id);
+    const validation = validateGraphDocument(graph, snapshot.dialect);
+    for (const block of blocks) {
+        const statement = contributions.find(c => c.id === block.contributionId)?.statement;
+        if (statement?.next && snapshot.workflow.composition.connections.filter(c => c.source.moduleId === block.id && c.source.portId === statement.next).length > 1) {
+            issues.push(`statement-output-shared:${block.id}`);
+        }
+        if (statement)
+            for (const [port, ref] of Object.entries(block.inputs)) {
+                if (!ref || typeof ref === 'string')
+                    continue;
+                const source = blocks.find(b => b.id === ref.moduleId);
+                const sourceStatement = contributions.find(c => c.id === source?.contributionId)?.statement;
+                if (port === statement.previous || statement.containers?.some(c => c.portId === port)) {
+                    if (sourceStatement?.next !== ref.portId)
+                        issues.push(`statement-source-not-representable:${block.id}:${port}`);
+                    const container = statement.containers?.find(c => c.portId === port);
+                    if (container) {
+                        let head = source;
+                        const seen = new Set();
+                        while (head && !seen.has(head.id)) {
+                            seen.add(head.id);
+                            const shape = contributions.find(c => c.id === head.contributionId)?.statement;
+                            const previous = shape?.previous ? head.inputs[shape.previous] : null;
+                            if (!previous || typeof previous === 'string')
+                                break;
+                            head = blocks.find(b => b.id === previous.moduleId);
+                        }
+                        const shape = contributions.find(c => c.id === head?.contributionId)?.statement;
+                        const check = container.check ?? statement.check, other = shape?.check;
+                        if (check && other && !(Array.isArray(check) ? check : [check]).some(c => (Array.isArray(other) ? other : [other]).includes(c)))
+                            issues.push(`statement-container-check-mismatch:${block.id}:${port}`);
+                    }
+                }
+                else if (snapshot.workflow.composition.connections.filter(c => c.source.moduleId === ref.moduleId && c.source.portId === ref.portId).length > 1) {
+                    issues.push(`statement-parameter-shared:${block.id}:${port}`);
+                }
+            }
+    }
+    if (!validation.valid)
+        issues.push(...validation.issues.filter(i => i.severity === 'error').map(i => `invalid-connection:${i.code}`));
+    return { layout, editable: issues.length === 0, issues: [...new Set(issues)], blocks };
+}
+/** Patch the existing canonical artifact; no whole-workflow roundtrip through a lossy graph encoding. */
+export function proposeBlocklyEdit(snapshot, contributions, reading) {
+    try {
+        const projection = projectBlocklyWorkflow(snapshot, contributions);
+        if (!projection.editable)
+            return failure(projection.issues.join('; '));
+        if (new Set(reading.map(b => b.id)).size !== reading.length)
+            return failure('duplicate-occurrence');
+        const candidate = structuredClone(snapshot.workflow);
+        const previousModules = snapshot.workflow.composition.modules;
+        candidate.composition.modules = reading.map(block => {
+            if (!/^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/.test(block.id))
+                throw new Error('invalid-occurrence-id');
+            const { contribution, definition } = resolve(snapshot, contributions, block.contributionId);
+            const previous = previousModules.find(m => m.id === block.id);
+            if (previous && previous.kind !== definition.type)
+                throw new Error('occurrence-definition-changed');
+            const module = previous ? structuredClone(previous) : nodalNodeToModule(createNodeFromDefinition({ definition, position: { x: 0, y: 0 } }));
+            if (!previous) {
+                module.id = block.id;
+                for (const port of module.ports) {
+                    port.moduleId = block.id;
+                    port.contract.id = `contract.${block.id}.${port.id}`;
+                }
+            }
+            const config = { ...(module.metadata?.config ?? {}) };
+            const fields = contribution.fields ?? [];
+            if (Object.keys(block.fields).some(key => !fields.some(f => f.configKey === key)))
+                throw new Error('unknown-config-field');
+            for (const field of fields) {
+                const value = block.fields[field.configKey];
+                if (typeof value !== (field.editor === 'text' ? 'string' : field.editor) || (typeof value === 'number' && !Number.isFinite(value)))
+                    throw new Error(`invalid-field:${field.configKey}`);
+                config[field.configKey] = value;
+            }
+            module.metadata = { ...module.metadata, config };
+            return module;
+        });
+        // Preserve authored module ordering, even if Blockly enumerates them in a different order.
+        const priorOrder = new Map(previousModules.map((m, i) => [m.id, i]));
+        candidate.composition.modules.sort((a, b) => (priorOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER) - (priorOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER));
+        candidate.composition.connections = [];
+        const usedChildren = new Set();
+        for (const block of reading) {
+            const { definition } = resolve(snapshot, contributions, block.contributionId);
+            if (Object.keys(block.inputs).some(id => !definition.inputs.some(p => p.id === id)))
+                throw new Error('unknown-input');
+            for (const [portId, reference] of Object.entries(block.inputs)) {
+                if (reference === null)
+                    continue;
+                const childId = typeof reference === 'string' ? reference : reference.moduleId;
+                const child = candidate.composition.modules.find(m => m.id === childId);
+                const outputs = child?.ports.filter(p => p.direction === 'output') ?? [];
+                const output = typeof reference === 'string' ? (outputs.length === 1 ? outputs[0] : undefined) : outputs.find(p => p.id === reference.portId);
+                if (!child || !output || (projection.layout === 'tree' && usedChildren.has(childId)))
+                    throw new Error('invalid-or-shared-child');
+                usedChildren.add(childId);
+                const previous = snapshot.workflow.composition.connections.find(c => c.source.moduleId === childId && c.source.portId === output.id && c.target.moduleId === block.id && c.target.portId === portId);
+                candidate.composition.connections.push(previous ? structuredClone(previous) : {
+                    id: `blockly.connection:${crypto.randomUUID()}`,
+                    source: { moduleId: childId, portId: output.id }, target: { moduleId: block.id, portId }
+                });
+            }
+        }
+        const edgeOrder = new Map(snapshot.workflow.composition.connections.map((c, i) => [c.id, i]));
+        candidate.composition.connections.sort((a, b) => (edgeOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER) - (edgeOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER));
+        const ids = new Set(candidate.composition.modules.map(m => m.id));
+        for (const domain of candidate.composition.domains)
+            domain.moduleIds = domain.moduleIds.filter(id => ids.has(id));
+        const oldPortContractIds = new Set(previousModules.flatMap(m => m.ports.map(p => p.contract.id)));
+        const nextPortContractIds = new Set(candidate.composition.modules.flatMap(m => m.ports.map(p => p.contract.id)));
+        candidate.composition.contracts = candidate.composition.contracts.filter(c => !oldPortContractIds.has(c.id) || nextPortContractIds.has(c.id));
+        for (const module of candidate.composition.modules.filter(m => !priorOrder.has(m.id))) {
+            for (const port of module.ports)
+                if (!candidate.composition.contracts.some(c => c.id === port.contract.id))
+                    candidate.composition.contracts.push(structuredClone(port.contract));
+        }
+        const check = projectBlocklyWorkflow({ ...snapshot, workflow: candidate }, contributions);
+        if (!check.editable)
+            return failure(check.issues.join('; '));
+        const nodalValidation = validateGraphDocument(projectWorkflowToNodalGraph(candidate), snapshot.dialect);
+        if (!nodalValidation.valid)
+            return failure(nodalValidation.issues.map(i => i.message).join('; '));
+        const commit = commitWorkflowComposition(snapshot.workflow, candidate);
+        if (!commit.accepted)
+            return failure(commit.validation.issues.map(i => i.message).join('; '));
+        return { accepted: true, candidate: commit.workflow, changed: JSON.stringify(commit.workflow) !== JSON.stringify(snapshot.workflow) };
+    }
+    catch (error) {
+        return failure(error instanceof Error ? error.message : 'invalid-projection');
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,17 @@
+import type { BlocklyEditorPort, NodalBlocklyHost, BlocklyPlaybackReading } from './contracts.js';
+import { BlocklyContributionCatalog } from './catalog.js';
+/** A disposable editing session, never the owner of the host or of its catalog. */
+export declare function createNodalBlocklySession(options: {
+    host: NodalBlocklyHost;
+    catalog: BlocklyContributionCatalog;
+    createEditor(): BlocklyEditorPort;
+    status?(message: string): void;
+}): {
+    activate(): void;
+    deactivate: () => void;
+    resize(): void;
+    highlight(moduleId: string | null): void;
+    presentPlayback(blocks: Readonly<Record<string, BlocklyPlaybackReading>>, label: (state: BlocklyPlaybackReading["state"]) => string): void;
+    run(): import("./contracts.js").BlocklyCommitResult;
+    dispose(): void;
+};

package/dist/session.js

@@ -0,0 +1,106 @@
+import { projectBlocklyWorkflow, proposeBlocklyEdit } from './projection.js';
+/** A disposable editing session, never the owner of the host or of its catalog. */
+export function createNodalBlocklySession(options) {
+    let editor = null;
+    let base = null;
+    let contributions = [];
+    let disposed = false, rendering = false;
+    let selectedModuleId = null;
+    const releases = [];
+    function select(moduleId) {
+        if (!editor || !base || rendering)
+            return;
+        selectedModuleId = moduleId;
+        options.host.select?.({ workflowId: base.workflow.id, revision: base.revision, moduleId });
+    }
+    function refresh() {
+        if (!editor)
+            return;
+        base = options.host.read();
+        base = base && { ...base, workflow: structuredClone(base.workflow) };
+        contributions = options.catalog.list();
+        rendering = true;
+        try {
+            const projection = base ? projectBlocklyWorkflow(base, contributions) : { editable: false, issues: ['no-workflow'], blocks: [] };
+            editor.render(projection, contributions, base);
+            options.status?.(projection.issues[0] ?? (contributions.length
+                ? (contributions.some(contribution => contribution.statement) ? 'ready-statements' :
+                    'layout' in projection && projection.layout === 'mixed' ? 'ready-mixed' :
+                        'layout' in projection && projection.layout === 'references' ? 'ready-references' : 'ready') : 'empty-catalog'));
+        }
+        finally {
+            rendering = false;
+        }
+    }
+    function commit() {
+        if (!editor || !base || rendering)
+            return;
+        const current = options.host.read();
+        if (!current || current.revision !== base.revision || current.workflow.id !== base.workflow.id) {
+            refresh();
+            options.status?.('source-changed');
+            return;
+        }
+        const proposal = proposeBlocklyEdit(base, contributions, editor.read());
+        if (!proposal.accepted) {
+            refresh();
+            options.status?.(proposal.reason);
+            return;
+        }
+        if (!proposal.changed)
+            return;
+        const result = options.host.commit({ baseRevision: base.revision, workflowId: base.workflow.id, candidate: proposal.candidate });
+        const selected = selectedModuleId;
+        refresh();
+        // A parameter edit of the selected occurrence can change its host focus.
+        // Foreign refreshes and viewport events never claim global selection.
+        if (result.accepted && selected && base?.workflow.composition.modules.some(module => module.id === selected))
+            select(selected);
+        if (!result.accepted)
+            options.status?.(result.reason);
+    }
+    function deactivate() {
+        for (const release of releases.splice(0).reverse())
+            release();
+        editor?.dispose();
+        editor = null;
+        base = null;
+        selectedModuleId = null;
+    }
+    return {
+        activate() {
+            if (disposed)
+                throw new Error('session-disposed');
+            if (editor)
+                return;
+            try {
+                editor = options.createEditor();
+                releases.push(options.host.subscribe(refresh));
+                releases.push(options.catalog.subscribe(refresh));
+                releases.push(editor.onSemanticChange(commit));
+                if (editor.onSelectionChange)
+                    releases.push(editor.onSelectionChange(select));
+                refresh();
+            }
+            catch (error) {
+                deactivate();
+                throw error;
+            }
+        },
+        deactivate,
+        resize() { editor?.resize(); },
+        highlight(moduleId) { editor?.highlight?.(moduleId); },
+        presentPlayback(blocks, label) { editor?.presentPlayback?.(blocks, label); },
+        run() {
+            const snapshot = options.host.read(), runtime = options.host.runtime;
+            if (!editor || !snapshot || !runtime)
+                return { accepted: false, reason: 'runtime-unavailable' };
+            const availability = runtime.availability(snapshot);
+            if (!availability.available)
+                return { accepted: false, reason: availability.reason ?? 'runtime-unavailable' };
+            return runtime.requestRun({ workflowId: snapshot.workflow.id, revision: snapshot.revision });
+        },
+        dispose() { if (disposed)
+            return; deactivate(); disposed = true; }
+    };
+}

package/dist/surface.d.ts

@@ -0,0 +1,22 @@
+import type { NodalBlocklyHost } from './contracts.js';
+import { BlocklyContributionCatalog } from './catalog.js';
+export interface NodalBlocklySurfaceOptions {
+    host: NodalBlocklyHost;
+    catalog: BlocklyContributionCatalog;
+    /** Translator belongs to the host; English defaults are the portable fallback. */
+    text?: (key: string, fallback: string) => string;
+    commands?: readonly {
+        label: string;
+        request(): {
+            accepted: boolean;
+            reason?: string;
+        };
+    }[];
+}
+/** Loading and mounting are explicit. Disposal also cancels an outstanding asynchronous load. */
+export declare function mountNodalBlocklySurface(element: HTMLElement, options: NodalBlocklySurfaceOptions): {
+    ready: Promise<void>;
+    deactivate(): void;
+    activate(): void;
+    dispose(): void;
+};