@nodegx/export 0.0.0-stage → 0.2.5

package/dist/emit/scaffold.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Scaffolding generator — EXP-002 implementation step 3: "a project that builds with an empty
+ * component proves the pipeline end to end."
+ *
+ * Emits everything around the components: package.json, Vite/TS config, entry point, the route
+ * table derived from the project's Router node(s) + each page's `Page` node urlPath, the design
+ * tokens as tokens.css, and a placeholder page per routed component so the output builds before
+ * the visual generator exists. Placeholders are explicitly marked and are replaced file-for-file
+ * as later generators land.
+ *
+ * Pure: ExportIR in, sorted { path → content } out. No filesystem access here — writing (and
+ * EXP-007's provenance headers/hashes, which need the final bytes) happens in a separate step.
+ */
+import { ExportIR } from '../ir/types';
+/**
+ * EXP-011 §54. The router shell kept as a component file for the logic beside its Router — an `On App Error`
+ * boundary — which `App.tsx` renders as the first child of the router, alive for the app's life.
+ */
+export interface ScaffoldShell {
+    symbol: string;
+    fileBase: string;
+}
+export interface ScaffoldPage {
+    /** Component path form: "Pages/Landing". */
+    componentPath: string;
+    /** "ThankYou" — PascalCased last path segment, deduplicated. */
+    fileBase: string;
+    /** "ThankYouPage". */
+    symbol: string;
+    /** "/thank-you", or "/product/{id}" — the component's Page node urlPath, verbatim. */
+    urlPath: string;
+    /**
+     * The same path as a react-router pattern: "/product/{id}" → "/product/:id".
+     *
+     * 🔴 **Not cosmetic — a braced segment matches nothing in react-router.** The runtime's own
+     * matcher splits on "/" and treats a `{name}` part as a capture (`router.tsx:746`); react-router
+     * spells the same thing `:name`. Emitting the authored path into `<Route path=…>` produced a
+     * route that only ever matched the literal text "{id}", so every detail page 404'd to the
+     * start page and the parameters this slice reads were never populated at all.
+     */
+    routePath: string;
+    /** The braced segment names, in path order — "/product/{id}/{tab}" → ["id", "tab"]. */
+    pathParams: string[];
+    isStart: boolean;
+}
+/**
+ * The braced segments of an authored urlPath, in order.
+ *
+ * ⚠️ Deliberately the runtime's own regex (`router.tsx:614`), not a stricter one. `Navigate To
+ * Path` uses `/\{[A-Za-z0-9_]*\}/g` — a narrower alphabet — and the two disagreeing is a
+ * runtime fact this export is not the place to resolve: a Page whose urlPath is `/x/{a-b}` has a
+ * parameter as far as the Router is concerned, so it has one here.
+ */
+export declare function bracedParams(urlPath: string): string[];
+export declare function emitScaffold(ir: ExportIR, shell?: ScaffoldShell): Record<string, string>;
+/**
+ * The route table: the first Router node's `routes` in source order, joined with each target
+ * component's `Page` node `urlPath`. Components a router lists but the project lacks are
+ * skipped here — analysis reports them (nothing in emit is allowed to throw on content).
+ */
+export declare function routedPages(ir: ExportIR): ScaffoldPage[];
+/**
+ * P18-S110-ROUTERSELF. What the export does not do with a Router's own ports, one sentence each. The Router collapses
+ * into `App.tsx` (`plan.ts` `routerShellDisposition`), which renders the pages straight into the route table: there
+ * is no Router element to paint, clip or class, and no Router to unmount.
+ */
+export declare function routerNotes(ir: ExportIR): string[];

package/dist/emit/statesLib.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `src/lib/states.ts` — the `States` node, emitted into the app (EXP-011 §49).
+ *
+ * {@link ./animateLib.ts}'s shape, one module over, and a module of its own because an app that
+ * fades a number should not ship a state machine. It imports `./animate` for the run engine, the
+ * bezier solver and the linear curve.
+ *
+ * It is a transcription of `noodl-viewer-react/src/nodes/std-library/states.ts`:
+ *
+ * - **Requests are queued per pass and drained after it** (`scheduleGoToState` over
+ *   `scheduleAfterInputsHaveUpdated`): a request for where the pass is already heading answers
+ *   Unchanged at once; otherwise all but the last request are *settled immediately* and the last
+ *   one animates. The drain here is a microtask — the handler that asked is the pass.
+ * - **`goToState`**: a falsy state is the first state; the current state is Unchanged; a name not
+ *   in the list is Failure, with the node's own `Error` text (`nearestName` transcribed for the
+ *   "Did you mean" clause); the first ever request jumps (no State Changed); after that booleans and
+ *   strings jump, numbers and colours tween along `transition-<state>-<value>`, else
+ *   `transitiondef-<state>`, else `{[0, 0, 0.58, 1], 300, 0}`, and settle at once when both are 0,
+ *   when Use Transitions is off, or when the state is one the pass only passed through. `State`,
+ *   `At <state>` and State Changed move at the request; `Has Reached <state>` at the tween's end
+ *   (at once when there is none); Done after State Changed.
+ * - **Colours** go through `resolveColor`, then `readColor` (the viewer's `color-reader.ts`,
+ *   transcribed), interpolate per channel with `Math.floor`, come back as `rgbaToHex`, and land on
+ *   the value the state names. Before GAM-006 (P88) the interpreter read every colour as hex, so a
+ *   `var(--token)` tweened through `#0aNaNNaNNaN`; it now reads the token off the document, as this
+ *   module always did. A colour unreadable at either end holds the colour on screen until the end,
+ *   in both worlds. The one departure left: this `resolveColor` also resolves a named colour
+ *   (`red`) through a probe element, so here it glides where the interpreter holds.
+ * - **A colour with a per-value delay holds the colour on screen for the delay.** Before GAM-006
+ *   (P88) both worlds published the tween's parsed RGBA array there (`currentValues[v] =
+ *   this.startValues[v]`), which no style sink accepts. Both now publish the start colour string.
+ * - **Boot** (`states`'s setter, then an authored `currentState`): the node jumps to the first
+ *   state, and an authored State that is not the first is a queued request — so it *animates* from
+ *   the first state at boot and fires State Changed. Reproduced.
+ */
+/** Where the module lands in the exported app. */
+export declare const STATES_LIB_PATH = "src/lib/states.ts";
+/** The exported helpers a component imports. Sorted — the import list is sorted too. */
+export declare const STATES_HELPERS: readonly ["defineStates", "useStates"];
+/** The value types this slice translates — `textStyle` is refused by name. */
+export declare const STATES_VALUE_TYPES: readonly ["number", "string", "boolean", "color"];
+export type StatesValueType = (typeof STATES_VALUE_TYPES)[number];
+/** The interpreter's default transition, `goToState`'s own literal. */
+export declare const DEFAULT_TRANSITION: {
+    readonly curve: readonly [0, 0, 0.58, 1];
+    readonly dur: 300;
+    readonly delay: 0;
+};
+/**
+ * The module's source — a plain string, for `dateLib.ts`'s stated reason.
+ */
+export declare function statesLibSource(): string;

package/dist/emit/style.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Style extraction — the per-node content-vs-style parameter split and the parameter → CSS
+ * mapping (EXP-002 step 4, semantics settled in EXP-002-TARGET-OUTPUT.md §1):
+ *
+ * - A node's parameters split into two piles: content/behaviour (text, src, alt, label, …) go to
+ *   JSX; layout and style go to one CSS-module class per visual node. The split is an explicit
+ *   table per visual type, never a guess.
+ * - Runtime style semantics become their CSS equivalents by table: `clip: true` →
+ *   `overflow: hidden`; `sizeMode` gates whether width/height are emitted; the `boxShadow*`
+ *   params fold into one `box-shadow` (missing pieces fall back to the catalog's port defaults,
+ *   because the interpreter falls back to the same); per-corner radii fold when uniform;
+ *   padding/margin use shorthands when the sides agree.
+ * - Token references (`var(--space-5)`) pass through verbatim; literals pass through literally;
+ *   `{value, unit}` dimensions join into CSS lengths (`0` stays unitless).
+ * - `Text` renders with `margin: 0`; flex containers state `display: flex` and their
+ *   `flex-direction` explicitly rather than relying on a global reset.
+ *
+ * Parameters that are neither content nor style (variant, cssClassName, mounted, …) are returned
+ * as `unhandled` — analysis reports them; nothing is silently dropped.
+ */
+import { CatalogIndex } from '../catalog';
+import { NodeIR, ParamValue, StylesIR } from '../ir/types';
+/** How a rendered node behaves for style purposes. */
+export type StyleRole = 'group' | 'text' | 'image' | 'button' | 'input' | 'page' | 'columns' | 'icon' | 'checkbox' | 'radio' | 'radiogroup' | 'select' | 'range' | 'video' | 'circle' | 'drag'
+/** EXP-011 §61. A Component Stack — a flex column that fills its parent and clips, as its `defaultCss` states. */
+ | 'stack';
+export interface Decl {
+    prop: string;
+    value: string;
+}
+export interface NodeStyle {
+    /** Ordered, ready to print. */
+    decls: Decl[];
+    /** Parameter names the style tables know nothing about — report, never guess. */
+    unhandled: string[];
+    /** Anything the tables dropped knowingly (unusable layout tokens, …) — report verbatim. */
+    notes: string[];
+}
+/** Pseudo/companion CSS a role owns beyond its one class (VISUALS-TARGET). */
+export interface RoleCss {
+    /** Printed as `.cls<suffix> { … }` right after the node's own block, decls hand-ordered. */
+    blocks: Array<{
+        suffix: string;
+        decls: Decl[];
+    }>;
+    /** A companion class beside the node's own: the control's label wrapper, the columns query container. */
+    wrapper?: {
+        role: 'label' | 'container';
+        decls: Decl[];
+    };
+    /** `@container (max-width: …)` overrides of the node's own class (columns breakpoints). */
+    containerQueries: Array<{
+        maxWidth: string;
+        decls: Decl[];
+    }>;
+    notes: string[];
+}
+/**
+ * The content/behaviour half of the split: parameters that bind into JSX rather than CSS,
+ * per visual type. `children` renders as the element's text child; `attr:<name>` as a JSX
+ * attribute; `head` as a hoisted document tag; `routing` is consumed by the route table.
+ */
+export declare const CONTENT_PARAMS: Record<string, Record<string, string>>;
+/** JSX attribute order per element, so generated attribute lists are stable and readable. */
+export declare const CONTENT_ATTR_ORDER: string[];
+/**
+ * The style parameters a **wire** may land on (EXP-011 §49) — printed as an inline `style={{…}}`
+ * on the element, which wins over the module class exactly as a wired value replaces the
+ * authored parameter in the runtime. `sink` is what the position holds, for the untyped-source
+ * table in `component.ts`; `css` is the React style key.
+ *
+ * Three, chosen by what the animation pair drives and by what needs no unit: `opacity` is
+ * unitless, the two colours are strings. A wired `width` would need the port's `defaultUnit`
+ * appended and a wired `transformX` a `transform` the static style has no rule for — both
+ * refused by name until a fixture asks. Keys in emit order.
+ *
+ * 🔴 **"Refused by name" was the intent and not the behaviour, for as long as this table existed
+ * (HLS-005).** Nothing here refuses anything: this is a lookup table, and `styleAttrs` iterates
+ * *it* rather than the bindings, so a wire onto a port that is not a key was never visited and so
+ * never named. The wire was dropped in silence and the component could still be filed under
+ * "Translated with nothing left over" — issue #23. The mechanism that makes this sentence true is
+ * the claim ledger and its sweep in `component.ts`, which reports every binding no builder took.
+ * `tests/fixtures/status-rail` is the fixture that asked.
+ */
+/**
+ * EXP-011 §63. A `Drag`'s own ports — the hook's options, printed by the component emitter and neither style nor
+ * content. ⚠️ `plan.ts`'s `DRAG_OPTION_PORTS` is the authority (it carries the keys and labels); this list must name the
+ * same ports, and `drag.test.ts` pins that it does. style.ts cannot import plan.ts (plan.ts imports this module).
+ */
+export declare const DRAG_OWN_PORTS: readonly string[];
+export declare const WIRED_STYLE_SINKS: Record<string, {
+    css: string;
+    sink: 'number' | 'string';
+}>;
+export declare function computeNodeStyle(node: NodeIR, role: StyleRole, catalog: CatalogIndex, 
+/**
+ * STY-004. The project's style dictionary, when it has one. Optional because 48 of this package's
+ * 48 fixtures and all seven shipped templates have none, and because every existing caller
+ * predates it — a node with no Look and no text style must compute byte-identically without it.
+ */
+styles?: StylesIR): NodeStyle;
+/**
+ * The layout string as grid tracks — `readLayoutToken`'s own rule (Columns.tsx): entries that
+ * are not positive finite numbers are dropped (reported here, where the runtime's validator
+ * cannot run), and a wholly unusable string renders one full-width column. An authored non-zero
+ * minWidth wraps each track in minmax(), the fold's floor spelled in CSS.
+ */
+export declare function layoutTracks(layoutString: string, minWidth: string | undefined, notes: string[]): string;
+/** Auto Fit's tracks; a zero/absent minimum degrades to one column, the runtime's own floor. */
+export declare function autoFitTracks(minWidth: string | undefined): string;
+/** The three `Noodl.Icon` shapes plus image sources, resolved from static parameters. */
+export type IconSource = {
+    kind: 'font';
+    classes: string[];
+    text?: string;
+} | {
+    kind: 'sprite';
+    url: string;
+    symbolId: string;
+} | {
+    kind: 'image';
+    src: string;
+} | {
+    kind: 'inline';
+} | {
+    kind: 'none';
+};
+export declare function iconSourceOf(node: NodeIR, catalog: CatalogIndex): IconSource;
+/**
+ * The CSS a role owns beyond its single class: control marks (::before), label wrappers, and
+ * the columns breakpoints' @container rules. Kept beside computeNodeStyle because the two must
+ * agree on effective values (border colour feeds both the box and the mark).
+ */
+export declare function computeRoleCss(node: NodeIR, role: StyleRole, catalog: CatalogIndex, 
+/**
+ * STY-004. The same dictionary `computeNodeStyle` gets, for the same reason this function sits
+ * beside it: a Look's `borderColor` has to reach the checkbox's mark as well as its box. Resolve
+ * it in one of the two and they disagree, which is the defect this pairing exists to prevent.
+ */
+styles?: StylesIR): RoleCss;
+/** Tokens and literals pass through verbatim; dimensions join value and unit; zero drops its unit. */
+export declare function cssValue(value: ParamValue): string;
+/**
+ * EXP-014. A `backgroundImage` port value as it must read inside `url(…)` in a generated CSS
+ * module.
+ *
+ * 🔴 **The leading slash is the whole function.** The port holds a project-relative path
+ * (`noodl_modules/starter-imagery/people-coffee-shop.webp`) and the asset travels through the
+ * `copies` channel to `public/<same path>`, which the bundler serves from the site root. A
+ * *relative* `url()` in CSS resolves against the stylesheet's own URL, not the document's, so the
+ * verbatim value would be resolved at build time against `src/pages/` and fail there. Root-
+ * absolute is the same shape `scaffold.ts` gives a module stylesheet's `<link href>`, and for the
+ * same reason.
+ *
+ * Anything already absolute — an http(s) URL, a protocol-relative one, a `data:` URI, or a path
+ * that already starts at the root — passes through untouched.
+ */
+export declare function cssUrl(value: string): string;
+/**
+ * EXP-014. `backdropBlur` as a CSS length, or `undefined` where the filter must not be emitted at
+ * all — the runtime's `cssLength` followed by its zero gate, transcribed. A `{value, unit}` from
+ * the editor and a bare number from a parameter are both lengths in px; a token reference is a
+ * string that is not a number, is not zero, and paints.
+ */
+export declare function blurLength(value: ParamValue | undefined): string | undefined;

package/dist/emit/utilLib.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `src/lib/util.ts` — the small string/math utilities, emitted into the app (EXP-011 Tier 2.7).
+ *
+ * The same shape as {@link ./dateLib.ts}, and for the same reason: `Substring`, `Number Remapper`
+ * and `String Mapper` are one pure function each, so what varies between two projects using them
+ * is only the arguments at the call site. Constant text here, shipped only where something calls
+ * into it.
+ *
+ * It is a transcription of three runtime files, and the transcription is the whole job:
+ *
+ * - `noodl-runtime/src/nodes/std-library/substring.ts` — the `-1` sentinel and the `substr` call.
+ * - `noodl-runtime/src/nodes/std-library/numberremapper.ts` — `_calculateNewOutputValue`, whose
+ *   degenerate branch (`maxInput === minInput ⇒ 0`) is reproduced rather than repaired. NDA-012
+ *   already decided that question in the interpreter, by moving the *default* off the degenerate
+ *   configuration; an export that silently answered something else would disagree with the node
+ *   an author has already watched run.
+ * - `noodl-runtime/src/nodes/std-library/stringmapper.ts` — `doMapping`, which is an `indexOf`
+ *   over two index-aligned lists.
+ *
+ * 🔴 **Two of the three take `unknown` where the runtime takes whatever arrived, and one place
+ * they deliberately disagree.** `Substring`'s `string` setter is `value.toString()`, which
+ * **throws** on `null`/`undefined` rather than yielding an empty result — the node's own port
+ * description says so. Reproducing that would put an uncaught exception in somebody's page, which
+ * is the trade the date family already refused (`dateLib.ts`, the enum paragraph). So the helper
+ * answers `''` there, and the planner files a note wherever a wire into that port can actually
+ * deliver an empty. For every value the interpreter survives, `String(v)` and `v.toString()` are
+ * the same string.
+ *
+ * ⚠️ **`Number()` rather than the raw arithmetic, and they agree.** The interpreter stores what
+ * arrives and lets `-` and `/` coerce. `Number(x)` and `x - 0` produce the same result for every
+ * primitive a port can carry — `''` and `null` to `0`, `undefined` and unparseable text to `NaN`
+ * — so the conversion is a typing device here and not a behaviour change.
+ */
+import { ParseHelper } from './parseLib';
+/** Where the module lands in the exported app. */
+export declare const UTIL_LIB_PATH = "src/lib/util.ts";
+/** The exported helpers, one per translated node. Sorted — the import list is sorted too. */
+export declare const UTIL_HELPERS: readonly ["blendColor", "blendColorKept", "booleanToString", "log", "mapString", "pickFile", "remapNumber", "substring"];
+/**
+ * A `util-call`'s verb. EXP-011 §75 widens it by the four parse helpers, which live in `src/lib/parse.ts`
+ * ({@link ./parseLib.ts}) and NOT in this module's source: the plan and the emitter treat the two families
+ * as one kind (a pure call, arguments in port order), and the import line is split by module at emit.
+ */
+export type UtilHelper = (typeof UTIL_HELPERS)[number] | ParseHelper;
+/**
+ * Which helpers can answer `undefined`, and it is exactly one.
+ *
+ * `substring` always returns a string and `remapNumber` always returns a number (`NaN` is a
+ * number, and `NaN` is what the interpreter publishes too). `mapString` publishes `Default` when
+ * nothing matched, and `Default` is unset on a node whose panel the author never opened — so it
+ * is the one read in this family a sink has to guard.
+ *
+ * 🔴 Must agree with `maybeUndefinedExpr` in `plan.ts` and `maybeUndefined` in `component.ts`;
+ * both read this table rather than restating it, which is the only spelling under which three
+ * copies of one fact cannot drift.
+ */
+export declare const UTIL_HELPER_MAY_BE_UNDEFINED: Record<UtilHelper, boolean>;
+/**
+ * Whether a `util-call` can answer `undefined` — {@link UTIL_HELPER_MAY_BE_UNDEFINED} for the utilities,
+ * and the parse module's per-output table for a parse helper (EXP-011 §75: `count` is never undefined,
+ * `items` is until the text arrives). 🔴 The one function both `maybeUndefinedExpr` (plan.ts) and
+ * `maybeUndefined` (component.ts) call, so the two cannot drift.
+ */
+export declare function utilCallMayBeUndefined(expr: {
+    fn: UtilHelper;
+    args: ReadonlyArray<{
+        kind: string;
+        value?: unknown;
+    }>;
+}): boolean;
+/**
+ * The module's source.
+ *
+ * ⚠️ A plain string rather than a template literal, for `dateLib.ts`'s stated reason: the emitted
+ * body needs no interpolation, and keeping it out of an interpolation context means a future edit
+ * cannot accidentally interpolate the generator's own scope into the exported app.
+ */
+export declare function utilLibSource(): string;

package/dist/errorMessage.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The message out of a thrown value, without asking which realm it was thrown in.
+ *
+ * ## 🔴 Why `instanceof Error` is not the way to do this (register row C41)
+ *
+ * `error instanceof Error ? error.message : String(error)` is the idiom everywhere, and it is
+ * **false for an error that crossed a realm boundary** — a different `vm` context, a jest sandbox,
+ * an Electron preload. When it is false the fallback runs, and `String(error)` is not
+ * `error.message`: it is `"SyntaxError: Unexpected token 'export'"` where the message alone is
+ * `"Unexpected token 'export'"`. So the *same* failure is reported to the *same* user in two
+ * different wordings, and which one they get depends on where the error was constructed.
+ *
+ * This was not a hypothesis. HLS-001 found it as an unexplained disagreement between two test
+ * runners over three hashes in the `kits` corpus project, and filed it as C41. HLS-002 hit it
+ * again from the other end: the editor's export and `nodegx export` produced byte-identical trees
+ * **except** `EXPORT-REPORT.md`, whose kit-loading lines differed by exactly this prefix. A
+ * defect that presents as "the two front doors disagree" is worth more than a defect that
+ * presents as a wording preference, which is why AC1 is written as a byte comparison.
+ *
+ * ⚠️ It is also load-bearing beyond the wording. `kitSource.ts` **pattern-matches** the string it
+ * gets here to decide whether a kit is an ES-module build. Those regexes happen to survive the
+ * prefix; the next one written might not, and it would fail by silently classifying a kit as
+ * something else rather than by throwing.
+ *
+ * The duck test below is realm-safe because it asks the value what it has rather than which
+ * constructor made it — which is the only question that has the same answer in every realm.
+ */
+export declare function errorMessage(error: unknown): string;