@konitif/nodal-blockly 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+# Licence — @konitif/nodal-blockly
+
+SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+
+The original KONITIF code in this v0.x package is made available under the
+PolyForm Noncommercial License 1.0.0:
+https://polyformproject.org/licenses/noncommercial/1.0.0
+
+This notice incorporates the standard terms by reference; it is not a modified
+version of the licence. This is source-available software, not OSI open source.
+Third-party components retain their own licences and notices.
+
+Uses outside the standard licence's permitted purposes require a separate
+written licence. A public repository or npm download grants no additional
+commercial rights. Any free professional authorization must be explicit,
+nominative and limited to the agreed products; none is granted by this notice.
+
+The KONITIF name, logo and official identity belong to Maxime Mouflard.
+Descriptive reference is permitted. No third-party version may claim to be
+official, certified or approved without authorization. This trademark notice
+is separate from the software licence and does not amend its terms.

package/README.md

@@ -0,0 +1,115 @@
+# @konitif/nodal-blockly
+
+A portable Blockly editing surface over KONITIF Nodal definitions and canonical Workflow Compositions. The package is distributed publicly on npm under the PolyForm Noncommercial License 1.0.0.
+
+The package exposes a Tool declaration, a host-scoped contribution catalog, a semantic projection adapter, a disposable session and a DOM surface. It imports no application store, domain-specific dialect, runtime or framework component. `blockly@12.1.0` is owned by this package and loaded only when its surface mounts. It does not load any JavaScript generator or evaluate generated source code.
+
+## Host the surface
+
+```ts
+import { BlocklyContributionCatalog } from '@konitif/nodal-blockly';
+import { mountNodalBlocklySurface } from '@konitif/nodal-blockly/surface';
+
+const catalog = new BlocklyContributionCatalog(); // Empty. No demonstration blocks are installed.
+const surface = mountNodalBlocklySurface(element, { host, catalog });
+await surface.ready;
+
+surface.deactivate(); // Releases the workspace, definitions and subscriptions.
+surface.activate();   // Re-reads the current canonical subject.
+surface.dispose();    // Terminal, idempotent; safe before ready resolves.
+catalog.dispose();   // Only the owner of this catalog disposes it.
+```
+
+The explicit host supplies `read`, `subscribe` and `commit`. It resolves the existing Nodal dialect and owns persistence and admission. A snapshot revision must change on every canonical update relevant to editing. `commit` must compare the base revision and subject identity, validate, then publish atomically; rejection must preserve the current canonical workflow and unrelated host artifact fields.
+
+The optional `runtime` port declares availability and delegates a run request to a common runtime. It is not required for editing. Without an admitted runtime provider, Run is disabled. Hosting the editor does not grant permission to operate external devices.
+
+A provider may expose `observe`/`subscribe` for execution state, the active
+canonical module ID, progress and errors, and `requestStop` for cancellation.
+The surface highlights that occurrence and renders Run/Stop/progress without
+owning execution or a clock. Per-block progress is projected top-to-bottom in
+a narrow gutter to the left of each instruction, matching statement-stack time
+without covering fields or changing Blockly geometry. Optional host `commands` expose explicit commands
+such as creating a program; mounting never creates or replaces a workflow.
+
+## Supply a projection contribution
+
+```ts
+const release = catalog.register('my-host-package', [{
+  id: 'my.number.block', dialectId: 'my.dialect', nodeType: 'my:number',
+  label: 'Number',
+  fields: [{ configKey: 'value', label: 'Value', editor: 'number' }]
+}]);
+// The matching definition, ports and defaultConfig come from host.read().dialect.
+release(); // Removes this lease only; existing workflows remain untouched.
+```
+
+Registration does not create a module occurrence. A placed block receives its own stable module ID and independent configuration. A contribution cannot change another occurrence's definition or invent a field missing from the shared schema. Catalog snapshots are copied, duplicate owners/projection IDs/node bindings are refused, and revoking an old lease cannot remove a later registration.
+
+## Supported editing projections
+
+- Native statement stacks and readable containers, explicitly bound to shared
+  input/output port IDs by `contribution.statement`. `previous`/`next` map the
+  predecessor relationship; each container maps its shared input to the tail
+  output of its contained stack. Reordering changes canonical connections, not
+  occurrence identities. Parameter values use genuine Blockly value sockets;
+  a text field may expose host-supplied dropdown choices. Presentation checks
+  assist snapping but never replace shared graph validation. Fan-out and
+  incompatible native statement structures are refused rather than duplicated.
+- Value-port trees with zero or one output per node, typed single-input connections and primitive configuration fields.
+- Mixed dialects combine native value sockets with explicit port-reference menus. A single-use source with one value output and value-only ports nests into a value input; shared sources remain one occurrence addressed by reference. Control/event inputs and multiple outputs stay explicit references, never an inferred Blockly statement order. Simple value dialects retain native trees; structured dialects without eligible value outputs retain reference cards.
+- Creation, field editing, connections and deletion, through common Nodal validation and `commitWorkflowComposition`, followed by host admission.
+- Stable workflow, composition, module and existing connection identities. Existing opaque metadata and canonical ordering are preserved.
+- Blockly coordinates and viewport are local to the projection. Moving a block does not update canonical state. The first version does not persist that layout after closing the surface.
+- Unknown projections, schema drift, disabled/locked nodes, cycles and composite references are reported as non-editable. Tree mode also refuses shared children; reference cards permit fan-out. Multiple incoming connections to one input and multiplicity contracts remain unsupported. Canonical data is retained; no silent partial rewrite occurs.
+
+This is an editing projection, not a runtime implementation. Control/event definitions must already exist in the host's shared dialect; this package does not install executors, infer scheduling or evaluate source code. The `BlocklyCompositeReference` extension records a definition revision, parameters, results, completion/error ports and the intended shared-definition/local-variant distinction. Composite editing is still explicitly refused. Hierarchical composition does not imply recursive runtime execution.
+
+`BlocklyBlockReading.inputs` accepts a legacy tree child ID, `null`, or an explicit `{ moduleId, portId }` output reference. `BlocklyProjection.layout` reports `tree`, `references` or `mixed`. Native connections in mixed mode read the same exact endpoint references as menus. Choosing a reference replaces an attached value; attaching a value clears the reference. Compatibility is decided by shared validation, including dialect-specific wildcard inputs; an incompatible gesture is restored from the host. These are disposable projection readings, not a second persisted workflow format. Edits clone and patch the canonical artifact, validate the complete graph and composition, and submit through the same host admission contract. Existing connections keep their IDs and opaque metadata; removing a source card disconnects its references. Primitive fields are editable; unexposed object/null-valued configuration is preserved.
+
+## Theme the surface
+
+The host may supply inherited CSS variables `--konitif-blockly-canvas`,
+`--konitif-blockly-surface`, `--konitif-blockly-ink`, `--konitif-blockly-muted`,
+`--konitif-blockly-border` and `--konitif-blockly-accent`. The workspace theme,
+flyout and surface chrome read these per-instance variables. Changing them
+does not recreate the workspace, register semantic definitions or commit a
+workflow revision. Without host variables, the portable light defaults apply.
+
+The paint-only Zelos specialization preserves native sockets, stacks and
+container geometry. Each block receives a non-interactive SVG depth path and
+a restrained gradient sheen; two shared gradient definitions are leased per
+workspace and released with its renderer. No blur, backdrop filter, frame loop
+or semantic observer is added. Base fills are slightly shaded to preserve
+white-label contrast. Vendor disabled patterns, shadow blocks, insertion
+markers, selection and execution highlighting retain their own meaning.
+
+Hosts may also supply `--konitif-blockly-block-border`,
+`--konitif-blockly-field-border`, `--konitif-blockly-depth` and
+`--konitif-blockly-sheen` (default `0.08`). Prefer a small sheen strength to keep
+labels readable. Forced-colour mode hides decorative paths and restores
+system-colour outlines. Theme updates do not recreate block identities.
+
+## Lifecycle and isolation
+
+Importing the package declares no workspace, subscription or registered block. Each mount installs uniquely namespaced block definitions; disposal removes only those names. Blockly's shared message table receives missing English defaults via a reference-counted mount lease; existing host translations win, and only still-owned additions are removed after the last release. Per-instance workspaces, resize observers, DOM handlers and subscriptions are released. Deactivation and reactivation are supported, and removal does not dispose a catalog owned by another host.
+
+## Verification
+
+Use Node 22 or newer:
+
+```sh
+npm ci --ignore-scripts
+npm run build
+npm test
+```
+
+The tests exercise the real Blockly renderer/workspaces in jsdom, including genuine block creation and field changes. SVG layout and canvas text measurement are stubbed because jsdom has no layout engine. They do not establish browser rendering quality or complete Behavior Studio integration. Reference definitions and executors exist only in test fixtures and are never installed into the shipped catalog.
+
+## Distribution
+
+The release authority is the standalone
+[`LeMouf/konitif-nodal-blockly`](https://github.com/LeMouf/konitif-nodal-blockly)
+repository. A merge does not publish the package. Releases require a reviewed
+archive, a matching protected version tag and the repository's protected npm
+publication workflow.

package/dist/catalog.d.ts

@@ -0,0 +1,12 @@
+import type { BlocklyNodeContribution } from './contracts.js';
+/** Host-scoped; import never registers global contributions. Empty by construction. */
+export declare class BlocklyContributionCatalog {
+    private entries;
+    private listeners;
+    private disposed;
+    list(): readonly BlocklyNodeContribution[];
+    register(owner: string, contributions: readonly BlocklyNodeContribution[]): () => void;
+    subscribe(listener: () => void): () => void;
+    dispose(): void;
+    private notify;
+}

package/dist/catalog.js

@@ -0,0 +1,51 @@
+/** Host-scoped; import never registers global contributions. Empty by construction. */
+export class BlocklyContributionCatalog {
+    entries = new Map();
+    listeners = new Set();
+    disposed = false;
+    list() {
+        return structuredClone([...this.entries.values()].flat());
+    }
+    register(owner, contributions) {
+        if (this.disposed)
+            throw new Error('catalog-disposed');
+        if (!owner.trim() || this.entries.has(owner))
+            throw new Error('duplicate-owner');
+        const all = [...this.list(), ...contributions];
+        if (new Set(all.map(c => c.id)).size !== all.length)
+            throw new Error('duplicate-contribution');
+        if (new Set(all.map(c => `${c.dialectId}\0${c.nodeType}`)).size !== all.length)
+            throw new Error('duplicate-node-projection');
+        for (const c of contributions) {
+            if (!c.id || !c.nodeType || !c.dialectId)
+                throw new Error('invalid-contribution');
+            if (new Set(c.fields?.map(f => f.configKey)).size !== (c.fields?.length ?? 0))
+                throw new Error('duplicate-field');
+        }
+        const lease = structuredClone(contributions);
+        this.entries.set(owner, lease);
+        this.notify();
+        return () => {
+            if (this.entries.get(owner) !== lease)
+                return;
+            this.entries.delete(owner);
+            this.notify();
+        };
+    }
+    subscribe(listener) {
+        if (this.disposed)
+            throw new Error('catalog-disposed');
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.entries.clear();
+        this.notify();
+        this.listeners.clear();
+    }
+    notify() { for (const listener of [...this.listeners])
+        listener(); }
+}

package/dist/contracts.d.ts

@@ -0,0 +1,135 @@
+import type { Workflow } from '@konitif/composition';
+import type { NodalDialect } from '@konitif/nodal';
+/** Presentation only: node meaning and port schema are resolved from the host dialect. */
+export interface BlocklyNodeContribution {
+    id: string;
+    dialectId: string;
+    nodeType: string;
+    label?: string;
+    colour?: string;
+    fields?: readonly {
+        configKey: string;
+        label: string;
+        editor: 'number' | 'text' | 'boolean';
+        options?: readonly {
+            label: string;
+            value: string;
+        }[];
+    }[];
+    composite?: BlocklyCompositeReference;
+    /** Native statement projection. Container inputs reference the tail of their stack.
+     * The host's shared dialect owns the meaning of these ports, not Blockly. */
+    statement?: {
+        previous?: string;
+        next?: string;
+        check?: string | string[];
+        containers?: readonly {
+            portId: string;
+            label: string;
+            check?: string | string[];
+        }[];
+    };
+}
+/** Extension contract. This first projection deliberately refuses composite editing/execution. */
+export interface BlocklyCompositeReference {
+    definition: {
+        workflowId: string;
+        revision: string;
+    };
+    parameters: readonly {
+        name: string;
+        portId: string;
+    }[];
+    results: readonly {
+        name: string;
+        portId: string;
+    }[];
+    completionPortId: string;
+    errorPortId: string;
+    editing: 'shared-definition' | 'local-variant';
+}
+export interface BlocklyWorkflowSnapshot {
+    /** Changes on any canonical update relevant to editing; opaque to the Tool. */
+    revision: string;
+    workflow: Workflow;
+    dialect: NodalDialect;
+}
+export interface BlocklyCommitRequest {
+    baseRevision: string;
+    workflowId: string;
+    candidate: Workflow;
+}
+export type BlocklyCommitResult = {
+    accepted: true;
+} | {
+    accepted: false;
+    reason: string;
+};
+/** Ephemeral host observation, never persisted or compiled into the Workflow. */
+export interface BlocklyPlaybackReading {
+    state: 'ready' | 'queued' | 'running' | 'paused' | 'completed' | 'failed';
+    progress: number;
+    warning?: {
+        message: string;
+    };
+}
+/** Host owns read, subscription, admission, persistence and optional common runtime. */
+export interface NodalBlocklyHost {
+    read(): BlocklyWorkflowSnapshot | null;
+    subscribe(listener: () => void): () => void;
+    commit(request: BlocklyCommitRequest): BlocklyCommitResult;
+    /** Ephemeral focus intent, never a semantic edit or a runtime command. */
+    select?(request: {
+        workflowId: string;
+        revision: string;
+        moduleId: string | null;
+    }): void;
+    runtime?: {
+        availability(snapshot: BlocklyWorkflowSnapshot): {
+            available: boolean;
+            reason?: string;
+        };
+        requestRun(request: {
+            workflowId: string;
+            revision: string;
+        }): BlocklyCommitResult;
+        /** Seek the canonical host transport using normalized sequence progress. */
+        requestSeek?(progress: number): BlocklyCommitResult;
+        requestStop?(): void;
+        observe?(): {
+            state: 'idle' | 'preparing' | 'running' | 'completed' | 'stopped' | 'failed';
+            activeModuleId?: string | null;
+            progress: number;
+            message?: string;
+            blocks?: Readonly<Record<string, BlocklyPlaybackReading>>;
+        };
+        subscribe?(listener: () => void): () => void;
+    };
+}
+export interface BlocklyBlockReading {
+    id: string;
+    contributionId: string;
+    fields: Record<string, string | number | boolean>;
+    /** Tree child ID (legacy), explicit output reference, or disconnected input. */
+    inputs: Record<string, string | {
+        moduleId: string;
+        portId: string;
+    } | null>;
+}
+export interface BlocklyProjection {
+    /** Reference cards preserve graph ports without inventing statement order. */
+    layout?: 'tree' | 'references' | 'mixed';
+    editable: boolean;
+    issues: string[];
+    blocks: BlocklyBlockReading[];
+}
+export interface BlocklyEditorPort {
+    render(projection: BlocklyProjection, contributions: readonly BlocklyNodeContribution[], snapshot: BlocklyWorkflowSnapshot | null): void;
+    read(): BlocklyBlockReading[];
+    onSemanticChange(listener: () => void): () => void;
+    onSelectionChange?(listener: (moduleId: string | null) => void): () => void;
+    resize(): void;
+    highlight?(moduleId: string | null): void;
+    presentPlayback?(blocks: Readonly<Record<string, BlocklyPlaybackReading>>, label: (state: BlocklyPlaybackReading['state']) => string): void;
+    dispose(): void;
+}

package/dist/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/editor.d.ts

@@ -0,0 +1,4 @@
+import type * as Blockly from 'blockly/core';
+import type { BlocklyEditorPort } from './contracts.js';
+/** Vendor adapter. All registered Blockly types are namespaced to this mount and released on disposal. */
+export declare function createBlocklyEditor(api: typeof Blockly, element: HTMLElement, messages?: Record<string, string>): BlocklyEditorPort;