capdag 1.306.150 → 1.361.331

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright © MachineFabric and contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -15,12 +15,17 @@ features.
 npm install capdag
 ```
 
-Node.js 14 or newer is required by the package manifest.
+The package is an ES module and needs Node.js 20 or newer. Dispatch,
+acceptance, equivalence and specificity are decided by code generated from the
+proved model ([formal foundations](https://capdag.com/docs/02-formal-foundations/)),
+which runs as WebAssembly: it is instantiated when the package is first
+imported, so importing it waits for that (top-level `await`), and a CommonJS
+`require` cannot load it.
 
 ## Parse and build Cap URNs
 
 ```javascript
-const { CapUrn, CapUrnBuilder } = require("capdag");
+import { CapUrn, CapUrnBuilder } from "capdag";
 
 const parsed = CapUrn.fromString(
   'cap:disbind;in="media:ext=pdf";out="media:enc=utf-8;page"'
@@ -42,13 +47,24 @@ equivalence, conformance, dispatch, and ranking instead of string surgery.
 - `capdag.js` provides URNs, definitions, dispatch, and matching.
 - `machine-parser.js` is generated from `machine.pegjs`.
 - `planner.js` provides planning and Machine Notation structures.
-- `cap-fab-renderer.js` and the browser build support graph presentation.
+- `cap-fab-renderer.js` (`capdag/cap-fab-renderer`) renders graphs; the page
+  provides cytoscape and cytoscape-elk.
+- `formal/` is the generated model code, with its WebAssembly program.
 - [`RULES.md`](RULES.md) records package-specific construction rules.
 
 The normative semantics and terminology live in the
-[CapDAG specification](https://github.com/machinefabric/capdag/blob/main/docs/01-overview.md). Source comments and
+[CapDAG specification](https://capdag.com/docs/01-overview/). Source comments and
 exports are the JavaScript API reference.
 
+## Use it in a browser
+
+`node build-browser.js <dir>` lays out capdag, tagged-urn and lungo-ts as ES
+modules a page loads without a bundler, each beside its WebAssembly program.
+A page imports `<dir>/capdag/capdag.js`, or — for page scripts that are not
+modules — imports `<dir>/capdag/browser.js` from a module script, which puts
+every public name on the global object once the models are instantiated. A page
+with a content security policy allows `script-src 'wasm-unsafe-eval'`.
+
 ## Build and verify changes
 
 ```bash

package/RULES.md

@@ -106,6 +106,6 @@ const result = await validateNoMediaDefRedefinition(mediaDefs, {
 ## Cross-Language Compatibility
 
 This JavaScript implementation follows the same rules as:
-- [Rust reference implementation](https://github.com/machinefabric/capdag)
+- [Rust reference implementation](https://github.com/machinefabric/capdag-rs)
 - [Go implementation](https://github.com/machinefabric/capdag-go)
 - [Objective-C implementation](https://github.com/machinefabric/capdag-objc)

package/build-browser.js

@@ -1,205 +1,108 @@
 #!/usr/bin/env node
-// Build browser-compatible bundles of tagged-urn, capdag, and
-// cap-fab-renderer from the local sources + resolved tagged-urn
-// dependency. Outputs three self-contained IIFE-wrapped JS files to
-// `dist/` that each expose their exported classes as window globals.
+// Lay out capdag, tagged-urn and lungo-ts for a browser: the ES modules as
+// they are, each beside the WebAssembly program it instantiates, with the
+// package names they import by rewritten to the paths they are laid out at —
+// so a page loads them without a bundler or an import map.
 //
-// The browser build exists because capdag-js source files are CJS:
-// they use `require()` and `module.exports`, which a plain <script tag>
-// cannot load. For browser consumers (capdag-dot-com, macfloom
-// WKWebViews) we strip those CJS hooks and wrap the result in an IIFE
-// that assigns to window.*.
+//   <outDir>/lungo-ts/        the WebAssembly host every generated program runs on
+//   <outDir>/tagged-urn/      tagged-urn.js and its model (formal/)
+//   <outDir>/capdag/          capdag.js, cap-fab-renderer.js and their model (formal/)
+//   <outDir>/capdag/browser.js
 //
-// Load order at the consumer:
-//   1. tagged-urn.js       — defines window.TaggedUrn, etc.
-//   2. capdag.js           — reads window.TaggedUrn, defines CapUrn,
-//                            MediaUrn, Cap, CapFab, createCap, …
-//   3. cap-fab-renderer.js — reads window.cytoscape + capdag globals
-//                              at call time, defines CapFabRenderer.
+// browser.js puts the public names of tagged-urn, capdag and the renderer on
+// the page's global object, for page scripts that are not modules
+// (capdag-dot-com, macfloom's web views). The programs are instantiated when
+// the modules are first imported, so a page imports browser.js from a module
+// script of its own and uses the globals after that import.
 //
 // Running: `node build-browser.js [outDir]`. Default outDir is ./dist.
 
-'use strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-const fs = require('fs');
-const path = require('path');
+const here = path.dirname(fileURLToPath(import.meta.url));
+const outDir = process.argv[2] ? path.resolve(process.argv[2]) : path.join(here, 'dist');
 
-const here = __dirname;
-const outDir = process.argv[2]
-  ? path.resolve(process.argv[2])
-  : path.join(here, 'dist');
-fs.mkdirSync(outDir, { recursive: true });
-
-function stripCJS(src) {
-  // Strip the CJS `Import TaggedUrn` comment and the trailing
-  // `module.exports = {...}` block, then rewrite any single-line
-  // `const { ... } = require('tagged-urn')` destructure into a
-  // destructure from `window`. The destructure may include any subset
-  // of names (TaggedUrn, valuesMatch, scoreTagValue, …) so long as it
-  // is one line; renames like `valuesMatch: taggedUrnValuesMatch` are
-  // preserved verbatim.
-  return src
-    .replace(/^\/\/.*Import TaggedUrn.*\n/m, '')
-    .replace(
-      /^const\s*(\{[^}]*\})\s*=\s*require\s*\(\s*['"]tagged-urn['"]\s*\)\s*;?\s*$/gm,
-      'const $1 = window;'
-    )
-    .replace(/^module\.exports\s*=\s*\{[\s\S]*?\};?\s*$/m, '');
-}
-
-function buildTaggedUrn() {
-  // tagged-urn is a sibling npm dependency. Resolve its main file.
-  const srcPath = require.resolve('tagged-urn');
-  const src = fs.readFileSync(srcPath, 'utf8');
-  const processed = src.replace(/^module\.exports\s*=\s*\{[\s\S]*?\};?\s*$/m, '');
-  const wrapped = `// tagged-urn — browser build
-// Generated from the tagged-urn npm package by capdag-js/build-browser.js.
-// Do not edit directly.
-
-(function() {
-'use strict';
-
-${processed}
-
-window.TaggedUrn = TaggedUrn;
-window.TaggedUrnBuilder = TaggedUrnBuilder;
-window.UrnMatcher = UrnMatcher;
-window.TaggedUrnError = TaggedUrnError;
-window.TaggedUrnErrorCodes = ErrorCodes;
-window.valuesMatch = valuesMatch;
-window.scoreTagValue = scoreTagValue;
-
-})();
-`;
-  fs.writeFileSync(path.join(outDir, 'tagged-urn.js'), wrapped);
-  console.log(`  wrote ${path.join(outDir, 'tagged-urn.js')}`);
+/** The directory of a package this one imports, as Node resolves it from here. */
+function packageDir(name, entry) {
+  const dir = path.dirname(fileURLToPath(import.meta.resolve(name)));
+  if (!fs.existsSync(path.join(dir, entry))) {
+    throw new Error(`${name} resolved to ${dir}, which has no ${entry}`);
+  }
+  return dir;
 }
 
-function buildCapdag() {
-  const srcPath = path.join(here, 'capdag.js');
-  const src = fs.readFileSync(srcPath, 'utf8');
-
-  const parserPath = path.join(here, 'machine-parser.js');
-  if (!fs.existsSync(parserPath)) {
-    throw new Error(`machine-parser.js not found at ${parserPath} — run 'npm run build:parser' first`);
+/**
+ * Copy `files` from `from` to `to`, replacing in each the import specifiers
+ * `rewrites` names for it. Every rewrite must apply: a source that no longer
+ * imports what this expects would otherwise ship still naming a package the
+ * browser cannot resolve.
+ */
+function lay(from, to, files, rewrites = {}) {
+  for (const file of files) {
+    const source = path.join(from, file);
+    const target = path.join(to, file);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const replacing = rewrites[file];
+    if (!replacing) {
+      fs.copyFileSync(source, target);
+      continue;
+    }
+    let text = fs.readFileSync(source, 'utf8');
+    for (const [specifier, replacement] of Object.entries(replacing)) {
+      const forms = [`from '${specifier}'`, `from "${specifier}"`];
+      const found = forms.filter((form) => text.includes(form));
+      if (found.length === 0) {
+        throw new Error(`${source} does not import '${specifier}', which the browser layout rewrites`);
+      }
+      for (const form of found) {
+        text = text.split(form).join(`from '${replacement}'`);
+      }
+    }
+    fs.writeFileSync(target, text);
   }
-  const parserSrc = fs.readFileSync(parserPath, 'utf8');
-
-  let processed = stripCJS(src);
-  // Replace the `const machineParser = require('./machine-parser.js')`
-  // line with a local variable the inlined parser assigns below.
-  processed = processed.replace(
-    /^const\s+machineParser\s*=\s*require\s*\(\s*['"]\.\/machine-parser\.js['"]\s*\)\s*;?\s*$/m,
-    '// machineParser is inlined above'
-  );
-
-  const inlinedParser = `
-// Inlined Peggy-generated machine parser.
-var machineParser = (function() {
-  var module = { exports: {} };
-  var exports = module.exports;
-${parserSrc}
-  return module.exports;
-})();
-`;
-
-  const wrapped = `// capdag — browser build
-// Generated from capdag-js/capdag.js by capdag-js/build-browser.js.
-// Do not edit directly. Requires tagged-urn.js loaded first.
-
-(function() {
-'use strict';
-
-if (!window.TaggedUrn) {
-  throw new Error('TaggedUrn global is not defined. Load tagged-urn.js before capdag.js.');
+  console.log(`  laid out ${to}`);
 }
 
-${inlinedParser}
-
-${processed}
-
-// Expose every public class and function as a window global.
-window.CapUrn = CapUrn;
-window.CapUrnBuilder = CapUrnBuilder;
-window.CapMatcher = CapMatcher;
-window.CapUrnError = CapUrnError;
-window.CapUrnErrorCodes = ErrorCodes;
-window.MediaUrn = MediaUrn;
-window.MediaUrnError = MediaUrnError;
-window.MediaUrnErrorCodes = MediaUrnErrorCodes;
-window.Cap = Cap;
-window.CapArg = CapArg;
-window.ArgSource = ArgSource;
-window.RegisteredBy = RegisteredBy;
-window.createCap = createCap;
-window.createCapWithDescription = createCapWithDescription;
-window.createCapWithMetadata = createCapWithMetadata;
-window.createCapWithDescriptionAndMetadata = createCapWithDescriptionAndMetadata;
-window.ValidationError = ValidationError;
-window.InputValidator = InputValidator;
-window.OutputValidator = OutputValidator;
-window.CapValidator = CapValidator;
-window.validateCapArgs = validateCapArgs;
-window.RESERVED_CLI_FLAGS = RESERVED_CLI_FLAGS;
-window.MediaDef = MediaDef;
-window.MediaDefError = MediaDefError;
-window.MediaDefErrorCodes = MediaDefErrorCodes;
-window.isBinaryCapUrn = isBinaryCapUrn;
-window.isJSONCapUrn = isJSONCapUrn;
-window.isStructuredCapUrn = isStructuredCapUrn;
-window.resolveMediaUrn = resolveMediaUrn;
-window.buildExtensionIndex = buildExtensionIndex;
-window.mediaUrnsForExtension = mediaUrnsForExtension;
-window.getExtensionMappings = getExtensionMappings;
-window.CapFabEdge = CapFabEdge;
-window.CapFabStats = CapFabStats;
-window.CapFab = CapFab;
-window.StdinSource = StdinSource;
-window.StdinSourceKind = StdinSourceKind;
-window.CapArgumentValue = CapArgumentValue;
-window.MachineSyntaxError = MachineSyntaxError;
-window.MachineSyntaxErrorCodes = MachineSyntaxErrorCodes;
-window.MachineEdge = MachineEdge;
-window.Machine = Machine;
-window.MachineBuilder = MachineBuilder;
-window.parseMachine = parseMachine;
-
-})();
-`;
-
-  fs.writeFileSync(path.join(outDir, 'capdag.js'), wrapped);
-  console.log(`  wrote ${path.join(outDir, 'capdag.js')}`);
+const taggedUrnDir = packageDir('tagged-urn', 'tagged-urn.js');
+const lungoTsDir = packageDir('lungo-ts', 'index.js');
+const parser = path.join(here, 'machine-parser.js');
+if (!fs.existsSync(parser)) {
+  throw new Error(`machine-parser.js not found at ${parser} — run 'npm run build:parser' first`);
 }
 
-function buildCapFabRenderer() {
-  const srcPath = path.join(here, 'cap-fab-renderer.js');
-  const src = fs.readFileSync(srcPath, 'utf8');
-  // The file's CJS exports block is at the bottom, guarded by
-  // `typeof module !== 'undefined'`. Strip everything from that guard
-  // to the end of the file.
-  const stripped = src.replace(
-    /if\s*\(\s*typeof\s+module\s*!==\s*'undefined'[\s\S]*$/,
-    ''
-  );
-  const wrapped = `// cap-fab-renderer — browser build
-// Generated from capdag-js/cap-fab-renderer.js by capdag-js/build-browser.js.
-// Do not edit directly. Requires cytoscape, cytoscape-elk, tagged-urn.js,
-// and capdag.js to be loaded first.
-
-(function() {
-'use strict';
+for (const dir of ['lungo-ts', 'tagged-urn', 'capdag']) {
+  fs.rmSync(path.join(outDir, dir), { recursive: true, force: true });
+}
 
-${stripped}
+const model = { 'formal/index.js': { 'lungo-ts': '../../lungo-ts/index.js' } };
 
-window.CapFabRenderer = CapFabRenderer;
+lay(lungoTsDir, path.join(outDir, 'lungo-ts'), ['index.js', 'wasi.js']);
+lay(taggedUrnDir, path.join(outDir, 'tagged-urn'),
+  ['tagged-urn.js', 'formal/index.js', 'formal/program.wasm'], model);
+lay(here, path.join(outDir, 'capdag'),
+  ['capdag.js', 'planner.js', 'machine-parser.js', 'cap-fab-renderer.js', 'formal/index.js', 'formal/program.wasm'],
+  { ...model, 'capdag.js': { 'tagged-urn': '../tagged-urn/tagged-urn.js' } });
 
-})();
-`;
-  fs.writeFileSync(path.join(outDir, 'cap-fab-renderer.js'), wrapped);
-  console.log(`  wrote ${path.join(outDir, 'cap-fab-renderer.js')}`);
-}
-
-buildTaggedUrn();
-buildCapdag();
-buildCapFabRenderer();
-console.log(`browser bundles written to ${outDir}`);
+fs.writeFileSync(path.join(outDir, 'capdag', 'browser.js'), `// Generated by capdag-js/build-browser.js. Do not edit.
+//
+// The public names of tagged-urn, capdag and the renderer, on the page's
+// global object. Import this from a module script; the names are there once
+// the import has completed.
+
+import * as taggedUrn from '../tagged-urn/tagged-urn.js';
+import * as capdag from './capdag.js';
+import { CapFabRenderer } from './cap-fab-renderer.js';
+
+// Both packages export an ErrorCodes; each is published under its own name.
+const { ErrorCodes: TaggedUrnErrorCodes, ...taggedUrnNames } = taggedUrn;
+const { ErrorCodes: CapUrnErrorCodes, ...capdagNames } = capdag;
+
+Object.assign(globalThis, taggedUrnNames, capdagNames, {
+  TaggedUrnErrorCodes,
+  CapUrnErrorCodes,
+  CapFabRenderer,
+});
+`);
+console.log(`browser modules written to ${outDir}`);

package/cap-fab-renderer.js

@@ -41,27 +41,19 @@
 // uses a different name for the same concept, the fix is at the producer,
 // not here.
 
-'use strict';
+import { CapUrn, CapFab, MediaUrn, createCap } from './capdag.js';
 
 // =============================================================================
-// Host dependencies — resolved at call time. When this file runs inside
-// Node (for tests) the globals are on `global`.
+// Host dependencies — the page's: cytoscape and cytoscape-elk, loaded as
+// scripts, resolved from the global object when a graph is drawn.
 // =============================================================================
 
 function requireHostDependency(name) {
-  const g = (typeof window !== 'undefined') ? window
-           : (typeof global !== 'undefined') ? global
-           : null;
-  if (g === null) {
-    throw new Error(
-      `CapFabRenderer: no global object (window/global) — cannot resolve '${name}'`
-    );
-  }
-  const value = g[name];
+  const value = globalThis[name];
   if (value === undefined) {
     throw new Error(
       `CapFabRenderer: required host dependency '${name}' is not loaded. ` +
-      `Load cytoscape, cytoscape-elk, tagged-urn.js, and capdag.js before this script.`
+      `Load cytoscape and cytoscape-elk before drawing a graph.`
     );
   }
   return value;
@@ -104,7 +96,6 @@ function cardinalityFromCap(cap) {
 // =============================================================================
 
 function canonicalMediaUrn(mediaUrnString) {
-  const MediaUrn = requireHostDependency('MediaUrn');
   return MediaUrn.fromString(mediaUrnString).toString();
 }
 
@@ -118,7 +109,6 @@ function mediaNodeLabel() {
 }
 
 function requireExplicitDisplayName(canonicalUrn, displayEntries, context) {
-  const MediaUrn = requireHostDependency('MediaUrn');
   const candidate = MediaUrn.fromString(canonicalUrn);
   for (const entry of displayEntries) {
     if (candidate.isEquivalent(entry.media)) return entry.display;
@@ -1159,9 +1149,6 @@ function annotateCrowdedBrowseEdges(edges) {
 function buildBrowseGraphData(capabilities) {
   validateBrowseData(capabilities);
 
-  const CapUrn = requireHostDependency('CapUrn');
-  const createCap = requireHostDependency('createCap');
-  const CapFab = requireHostDependency('CapFab');
 
   const nodesMap = new Map();
   const edges = [];
@@ -1328,7 +1315,6 @@ function buildStrandGraphData(data) {
   // Look up a display name for a media URN via the host-supplied map.
   // Uses `MediaUrn.isEquivalent` so tag-order variation doesn't defeat
   // the lookup — URNs are compared semantically, never as raw strings.
-  const MediaUrn = requireHostDependency('MediaUrn');
   const displayEntries = [];
   for (const [urn, display] of Object.entries(mediaDisplayNames)) {
     if (typeof display !== 'string' || display.length === 0) continue;
@@ -1652,7 +1638,6 @@ function buildStrandGraphData(data) {
 //      cap edge lands on that merged endpoint. Removes the visible
 //      duplicate node.
 function collapseStrandShapeTransitions(built) {
-  const MediaUrn = requireHostDependency('MediaUrn');
 
   // Index for lookups.
   const nodeById = new Map();
@@ -1817,7 +1802,6 @@ function strandCytoscapeElements(built, options) {
 // matches the supplied URN string. Uses CapUrn.isEquivalent — never
 // string equality.
 function findCapStepIndexByUrn(steps, targetUrnString) {
-  const CapUrn = requireHostDependency('CapUrn');
   const target = CapUrn.fromString(targetUrnString);
   for (let i = 0; i < steps.length; i++) {
     const variant = Object.keys(steps[i].step_type)[0];
@@ -2171,7 +2155,6 @@ function buildRunGraphData(data) {
   // Look up a display name for a media URN via the host-supplied
   // `media_display_names` map. Uses `MediaUrn.isEquivalent` for
   // semantic URN equality.
-  const MediaUrn = requireHostDependency('MediaUrn');
   const mediaDisplayNames = data.media_display_names || {};
   const displayEntries = [];
   for (const [urn, display] of Object.entries(mediaDisplayNames)) {
@@ -3649,7 +3632,6 @@ class CapFabRenderer {
       return;
     }
 
-    const CapUrn = requireHostDependency('CapUrn');
     const target = CapUrn.fromString(this._capUrnString(cap));
 
     for (const [edgeId, edgeCap] of this.capabilitiesByEdgeId) {
@@ -3691,7 +3673,6 @@ class CapFabRenderer {
   getEdgeDataByCapUrn(capUrnString) {
     if (this.mode !== 'browse') return null;
     if (!this.cy || typeof capUrnString !== 'string' || capUrnString.length === 0) return null;
-    const CapUrn = requireHostDependency('CapUrn');
     const target = CapUrn.fromString(capUrnString);
     for (const [edgeId, edgeCap] of this.capabilitiesByEdgeId) {
       const candidate = CapUrn.fromString(edgeCap.urn);
@@ -3708,7 +3689,6 @@ class CapFabRenderer {
       throw new Error(`CapFabRenderer: selectEdgeByCapUrn is only valid in browse mode (current: ${this.mode})`);
     }
     if (!this.cy || typeof capUrnString !== 'string' || capUrnString.length === 0) return;
-    const CapUrn = requireHostDependency('CapUrn');
     const target = CapUrn.fromString(capUrnString);
     for (const [edgeId, edgeCap] of this.capabilitiesByEdgeId) {
       const candidate = CapUrn.fromString(edgeCap.urn);
@@ -4067,30 +4047,26 @@ class CapFabRenderer {
 }
 
 // =============================================================================
-// Module exports — CJS for Node tests. Browser-side the build-browser.js
-// concatenation wraps these declarations in an IIFE and assigns
-// `window.CapFabRenderer`.
+// Module exports
 // =============================================================================
 
-if (typeof module !== 'undefined' && module.exports) {
-  module.exports = {
-    CapFabRenderer,
-    cardinalityLabel,
-    cardinalityFromCap,
-    canonicalMediaUrn,
-    mediaNodeLabel,
-    buildBrowseGraphData,
-    buildStrandGraphData,
-    collapseStrandShapeTransitions,
-    buildRunGraphData,
-    buildEditorGraphData,
-    buildResolvedMachineGraphData,
-    classifyStrandCapSteps,
-    validateStrandPayload,
-    validateRunPayload,
-    validateEditorGraphPayload,
-    validateResolvedMachinePayload,
-    validateStrandStep,
-    validateBodyOutcome,
-  };
-}
+export {
+  CapFabRenderer,
+  cardinalityLabel,
+  cardinalityFromCap,
+  canonicalMediaUrn,
+  mediaNodeLabel,
+  buildBrowseGraphData,
+  buildStrandGraphData,
+  collapseStrandShapeTransitions,
+  buildRunGraphData,
+  buildEditorGraphData,
+  buildResolvedMachineGraphData,
+  classifyStrandCapSteps,
+  validateStrandPayload,
+  validateRunPayload,
+  validateEditorGraphPayload,
+  validateResolvedMachinePayload,
+  validateStrandStep,
+  validateBodyOutcome,
+};