@gyral/core 0.2.0 → 0.3.1

package/dist/props.js

@@ -1,44 +1,167 @@
-/** The element's declared props as set on it (no defaults): what a seed must carry. */
-export function readRawProps(el, table) {
-    const self = el;
-    return Object.fromEntries(Object.keys(table).map((name) => [name, self[name]]));
-}
-/** The element's declared props as components see them: `default` fills `undefined`. */
-export function readProps(el, table) {
-    const self = el;
-    return Object.fromEntries(Object.entries(table).map(([name, info]) => {
-        const value = self[name];
-        return [name, value === undefined && 'default' in info ? info.default : value];
-    }));
-}
-/** Required props that are still `undefined` (ADR 0007 addendum). */
-export function missingRequired(el, table) {
-    const self = el;
-    return Object.entries(table)
-        .filter(([name, info]) => info.required === true && self[name] === undefined)
-        .map(([name]) => name);
-}
-/** True when every declared prop is identical (`Object.is`) in both snapshots. */
-export function sameProps(names, a, b) {
-    return names.every((name) => Object.is(a[name], b[name]));
-}
-/** Hydration: sets props that only travelled in the seed, unless the page already set them. */
-export function restoreProps(el, names, seeded) {
-    const self = el;
-    for (const [name, value] of Object.entries(seeded)) {
-        if (names.includes(name) && self[name] === undefined)
-            self[name] = value;
+import { DEV, message } from './view/index.js';
+/** `minPrice` → `min-price`. */
+export const kebab = (name) => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+/** The prop's attribute, or undefined for a property-only prop. */
+export function attributeOf(name, def) {
+    if (def.attribute === false)
+        return undefined;
+    return def.attribute ?? kebab(name);
+}
+const builtIn = {
+    string: (v) => typeof v === 'string',
+    number: (v) => typeof v === 'number' && !Number.isNaN(v),
+    boolean: (v) => typeof v === 'boolean',
+};
+/** Runs the built-in type check and the prop's schema. Schemas must be synchronous. */
+export function checkValue(tag, name, def, value) {
+    const typeOk = builtIn[def.kind];
+    if (typeOk !== undefined && !typeOk(value)) {
+        return {
+            ok: false,
+            issues: [`expected a ${def.kind}, got ${typeof value}`],
+        };
+    }
+    const schema = def.schema;
+    if (schema === undefined)
+        return { ok: true, value };
+    // A type guard (prop.value/prop.json, gyral-c5d.7); ArkType-style callable schemas have ~standard.
+    if (!('~standard' in schema)) {
+        return schema(value) ? { ok: true, value } : { ok: false, issues: [`failed ${schema.name}`] };
+    }
+    const result = schema['~standard'].validate(value);
+    if (result instanceof Promise) {
+        throw new TypeError(message(20, tag, name));
+    }
+    if (result.issues !== undefined)
+        return { ok: false, issues: result.issues.map((i) => i.message) };
+    return { ok: true, value: result.value };
+}
+/** Parses an attribute value (`null`: absent) per the builder table; undefined means missing. */
+export function parseAttribute(def, raw) {
+    if (def.kind === 'boolean')
+        return { ok: true, value: raw !== null };
+    if (raw === null)
+        return undefined;
+    if (def.kind === 'number') {
+        const n = raw.trim() === '' ? Number.NaN : Number(raw);
+        return Number.isNaN(n)
+            ? { ok: false, issues: [`"${raw}" is not a number`] }
+            : { ok: true, value: n };
+    }
+    if (def.kind === 'json') {
+        try {
+            return { ok: true, value: JSON.parse(raw) };
+        }
+        catch {
+            return { ok: false, issues: ['the attribute is not valid JSON'] };
+        }
+    }
+    return { ok: true, value: raw };
+}
+/** Logs an invalid value; the caller then treats the prop as missing. */
+export function reportInvalid(tag, name, from, issues) {
+    console.error(message(21, tag, name, from, issues.join('; ')));
+}
+/**
+ * An attribute's value for prop `name` (view/05-element.md "When props are validated"):
+ * parsed per the builder and always validated; invalid or absent values are missing.
+ */
+export function attributeValue(tag, name, def, attr, raw) {
+    const parsed = def === undefined ? undefined : parseAttribute(def, raw);
+    if (def === undefined || parsed === undefined)
+        return undefined;
+    const checked = parsed.ok ? checkValue(tag, name, def, parsed.value) : parsed;
+    if (checked.ok)
+        return checked.value;
+    reportInvalid(tag, name, `the attribute ${attr}`, checked.issues);
+    return undefined;
+}
+/**
+ * A property set's (or seed's) value for prop `name`: validated in development only, where an
+ * invalid value is missing and a schema that transforms warns. Production keeps the input
+ * without calling this (propFeature, element.ts: gyral-c5d.14).
+ */
+export function propertyValue(tag, name, def, value, from = 'a property') {
+    if (!DEV || value === undefined || def === undefined)
+        return value;
+    const checked = checkValue(tag, name, def, value);
+    if (!checked.ok) {
+        reportInvalid(tag, name, from, checked.issues);
+        return undefined;
+    }
+    if (!sameData(checked.value, value)) {
+        console.warn(`<${tag}> prop "${name}": its schema transformed the value from ${from}. Production ` +
+            "doesn't run schemas on property sets; validate, don't transform.");
+    }
+    return value;
+}
+/** Structural equality for plain data (arrays, plain objects), `Object.is` for the rest. */
+export function sameData(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    if (Array.isArray(a)) {
+        return Array.isArray(b) && a.length === b.length && a.every((x, i) => sameData(x, b[i]));
+    }
+    if (Object.getPrototypeOf(a) !== Object.prototype ||
+        Object.getPrototypeOf(b) !== Object.prototype) {
+        return false;
+    }
+    const ka = Object.keys(a);
+    return (ka.length === Object.keys(b).length && ka.every((k) => sameData(a[k], b[k])));
+}
+/** The declared props as components see them: `default` fills missing values. */
+export function readProps(values, table) {
+    const out = {};
+    for (const [name, def] of Object.entries(table)) {
+        const value = values[name];
+        out[name] = value === undefined ? def.default : value;
+    }
+    return out;
+}
+/** Required props that are still missing (ADR 0007 addendum). */
+export function missingRequired(values, table) {
+    return Object.keys(table).filter((name) => table[name]?.required === true && values[name] === undefined);
+}
+/** Warns about required props that are still missing, at first render. */
+export function warnMissing(tag, values, table) {
+    const missing = missingRequired(values, table);
+    if (missing.length > 0) {
+        console.warn(message(22, tag, missing.join(', ')));
     }
 }
 /**
- * Declared props that collide with a built-in element property (`hidden`, `title`, `id`, …).
- * Lit's reactive accessor replaces the built-in, so setting the prop silently changes what the
- * platform does with it: a prop named `hidden` hides the element (gyral-czi.33). Browser only:
- * the server's DOM shim doesn't model the full prototype chain.
+ * Declared props that collide with a built-in element property (`hidden`, `title`, `id`, …):
+ * the accessor replaces the built-in, so setting the prop silently changes what the platform
+ * does with it (gyral-czi.33).
  */
 export function shadowedBuiltins(names) {
     if (typeof HTMLElement === 'undefined')
         return [];
     return names.filter((name) => name in HTMLElement.prototype);
 }
+/** define(): a prop named like a built-in property is an error in development, else a warning. */
+export function checkShadowed(tag, names) {
+    const shadowed = shadowedBuiltins(names);
+    if (shadowed.length === 0)
+        return;
+    const text = message(23, tag, shadowed.join(', '));
+    if (DEV)
+        throw new TypeError(text);
+    console.warn(text);
+}
+/**
+ * What the element uses, registered by the prop builders (features.ts). Property sets and seeds
+ * go through `propertyValue` in development only: production keeps the value as given, so the
+ * property path's schema and guard handling stay out of production bundles (gyral-c5d.14).
+ */
+export const propFeature = {
+    attributeOf,
+    attributeValue,
+    propertyValue: DEV ? propertyValue : undefined,
+    warnMissing,
+    readProps,
+    checkShadowed,
+};
 //# sourceMappingURL=props.js.map

package/dist/props.js.map

@@ -1 +1 @@
-{"version":3,"file":"props.js","sourceRoot":"","sources":["../src/props.ts"],"names":[],"mappings":"AAaA,uFAAuF;AACvF,MAAM,UAAU,YAAY,CAAC,EAAU,EAAE,KAAgB;IACvD,MAAM,IAAI,GAAG,EAAS,CAAC;IACvB,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAClF,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,SAAS,CAAC,EAAU,EAAE,KAAgB;IACpD,MAAM,IAAI,GAAG,EAAS,CAAC;IACvB,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,IAAI,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACjF,CAAC,CAAC,CACH,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,eAAe,CAAC,EAAU,EAAE,KAAgB;IAC1D,MAAM,IAAI,GAAG,EAAS,CAAC;IACvB,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SACzB,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC;SAC5E,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,SAAS,CAAI,KAAwB,EAAE,CAAI,EAAE,CAAI;IAC/D,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAE,CAAS,CAAC,IAAI,CAAC,EAAG,CAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,YAAY,CAAC,EAAU,EAAE,KAAwB,EAAE,MAAW;IAC5E,MAAM,IAAI,GAAG,EAA6B,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IAC3E,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAwB;IACvD,IAAI,OAAO,WAAW,KAAK,WAAW;QAAE,OAAO,EAAE,CAAC;IAClD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC;AAC/D,CAAC","sourcesContent":["// Prop bookkeeping for define() (ADR 0007): snapshots, defaults, change detection, seed restore.\nimport type { PropertyDeclaration } from 'lit';\n\ntype Bag = Readonly<Record<string, unknown>>;\n\n/** Gyral's view of a declaration: Lit's options plus `required` and `default`. */\nexport interface PropInfo extends PropertyDeclaration {\n  readonly required?: boolean;\n  readonly default?: unknown;\n}\n\nexport type PropTable = Readonly<Record<string, PropInfo>>;\n\n/** The element's declared props as set on it (no defaults): what a seed must carry. */\nexport function readRawProps(el: object, table: PropTable): Bag {\n  const self = el as Bag;\n  return Object.fromEntries(Object.keys(table).map((name) => [name, self[name]]));\n}\n\n/** The element's declared props as components see them: `default` fills `undefined`. */\nexport function readProps(el: object, table: PropTable): Bag {\n  const self = el as Bag;\n  return Object.fromEntries(\n    Object.entries(table).map(([name, info]) => {\n      const value = self[name];\n      return [name, value === undefined && 'default' in info ? info.default : value];\n    }),\n  );\n}\n\n/** Required props that are still `undefined` (ADR 0007 addendum). */\nexport function missingRequired(el: object, table: PropTable): string[] {\n  const self = el as Bag;\n  return Object.entries(table)\n    .filter(([name, info]) => info.required === true && self[name] === undefined)\n    .map(([name]) => name);\n}\n\n/** True when every declared prop is identical (`Object.is`) in both snapshots. */\nexport function sameProps<P>(names: readonly string[], a: P, b: P): boolean {\n  return names.every((name) => Object.is((a as Bag)[name], (b as Bag)[name]));\n}\n\n/** Hydration: sets props that only travelled in the seed, unless the page already set them. */\nexport function restoreProps(el: object, names: readonly string[], seeded: Bag): void {\n  const self = el as Record<string, unknown>;\n  for (const [name, value] of Object.entries(seeded)) {\n    if (names.includes(name) && self[name] === undefined) self[name] = value;\n  }\n}\n\n/**\n * Declared props that collide with a built-in element property (`hidden`, `title`, `id`, …).\n * Lit's reactive accessor replaces the built-in, so setting the prop silently changes what the\n * platform does with it: a prop named `hidden` hides the element (gyral-czi.33). Browser only:\n * the server's DOM shim doesn't model the full prototype chain.\n */\nexport function shadowedBuiltins(names: readonly string[]): string[] {\n  if (typeof HTMLElement === 'undefined') return [];\n  return names.filter((name) => name in HTMLElement.prototype);\n}\n"]}
+{"version":3,"file":"props.js","sourceRoot":"","sources":["../src/props.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAM/C,gCAAgC;AAChC,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;AAEpG,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,GAAkB;IAC1D,IAAI,GAAG,CAAC,SAAS,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IAC9C,OAAO,GAAG,CAAC,SAAS,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC;AAMD,MAAM,OAAO,GAAsD;IACjE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ;IACpC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACxD,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,SAAS;CACvC,CAAC;AAEF,uFAAuF;AACvF,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,IAAY,EAAE,GAAkB,EAAE,KAAc;IACtF,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3C,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,CAAC,cAAc,GAAG,CAAC,IAAI,SAAS,OAAO,KAAK,EAAE,CAAC;SACxD,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAC1B,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACrD,mGAAmG;IACnG,IAAI,CAAC,CAAC,WAAW,IAAI,MAAM,CAAC,EAAE,CAAC;QAC7B,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,UAAU,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;IAChG,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACnD,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;QAC9B,MAAM,IAAI,SAAS,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;QAC7B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACpE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;AAC3C,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,cAAc,CAAC,GAAkB,EAAE,GAAkB;IACnE,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,KAAK,IAAI,EAAE,CAAC;IACrE,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACnC,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACpB,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,IAAI,GAAG,mBAAmB,CAAC,EAAE;YACrD,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC7B,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,EAAE,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,iCAAiC,CAAC,EAAE,CAAC;QACpE,CAAC;IACH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AAClC,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,IAAY,EAAE,IAAY,EAAE,MAAyB;IAC9F,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAW,EACX,IAAY,EACZ,GAA8B,EAC9B,IAAY,EACZ,GAAkB;IAElB,MAAM,MAAM,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACxE,IAAI,GAAG,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAChE,MAAM,OAAO,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9E,IAAI,OAAO,CAAC,EAAE;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC;IACrC,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,iBAAiB,IAAI,EAAE,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAClE,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAW,EACX,IAAY,EACZ,GAA8B,EAC9B,KAAc,EACd,IAAI,GAAG,YAAY;IAEnB,IAAI,CAAC,GAAG,IAAI,KAAK,KAAK,SAAS,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACnE,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;QAChB,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/C,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;QACpC,OAAO,CAAC,IAAI,CACV,IAAI,GAAG,WAAW,IAAI,4CAA4C,IAAI,eAAe;YACnF,kEAAkE,CACrE,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,QAAQ,CAAC,CAAU,EAAE,CAAU;IAC7C,IAAI,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC7F,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3F,CAAC;IACD,IACE,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,SAAS;QAC7C,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,SAAS,EAC7C,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,OAAO,CACL,EAAE,CAAC,MAAM,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAE,CAAS,CAAC,CAAC,CAAC,EAAG,CAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAC/F,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,SAAS,CAAC,MAAW,EAAE,KAAgB;IACrD,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3B,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;IACxD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,eAAe,CAAC,MAAW,EAAE,KAAgB;IAC3D,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAC9B,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,SAAS,CACvE,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,MAAW,EAAE,KAAgB;IACpE,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC/C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAwB;IACvD,IAAI,OAAO,WAAW,KAAK,WAAW;QAAE,OAAO,EAAE,CAAC;IAClD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC;AAC/D,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,KAAwB;IACjE,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACzC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAClC,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACnD,IAAI,GAAG;QAAE,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,WAAW;IACX,cAAc;IACd,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS;IAC9C,WAAW;IACX,SAAS;IACT,aAAa;CACd,CAAC","sourcesContent":["// Prop bookkeeping for define() (view/05-element.md \"Props\", ADR 0007): attribute names and\n// parsing, validation through Standard Schema, defaults, change detection, seed restore. The\n// prop builders register `propFeature` (features.ts): components without props don't bundle it.\nimport type { Prop } from './prop.js';\nimport { DEV, message } from './view/index.js';\n\ntype Bag = Readonly<Record<string, unknown>>;\n\nexport type PropTable = Readonly<Record<string, Prop<unknown>>>;\n\n/** `minPrice` → `min-price`. */\nexport const kebab = (name: string): string => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);\n\n/** The prop's attribute, or undefined for a property-only prop. */\nexport function attributeOf(name: string, def: Prop<unknown>): string | undefined {\n  if (def.attribute === false) return undefined;\n  return def.attribute ?? kebab(name);\n}\n\nexport type Checked =\n  | { readonly ok: true; readonly value: unknown }\n  | { readonly ok: false; readonly issues: readonly string[] };\n\nconst builtIn: Readonly<Record<string, (v: unknown) => boolean>> = {\n  string: (v) => typeof v === 'string',\n  number: (v) => typeof v === 'number' && !Number.isNaN(v),\n  boolean: (v) => typeof v === 'boolean',\n};\n\n/** Runs the built-in type check and the prop's schema. Schemas must be synchronous. */\nexport function checkValue(tag: string, name: string, def: Prop<unknown>, value: unknown): Checked {\n  const typeOk = builtIn[def.kind];\n  if (typeOk !== undefined && !typeOk(value)) {\n    return {\n      ok: false,\n      issues: [`expected a ${def.kind}, got ${typeof value}`],\n    };\n  }\n  const schema = def.schema;\n  if (schema === undefined) return { ok: true, value };\n  // A type guard (prop.value/prop.json, gyral-c5d.7); ArkType-style callable schemas have ~standard.\n  if (!('~standard' in schema)) {\n    return schema(value) ? { ok: true, value } : { ok: false, issues: [`failed ${schema.name}`] };\n  }\n  const result = schema['~standard'].validate(value);\n  if (result instanceof Promise) {\n    throw new TypeError(message(20, tag, name));\n  }\n  if (result.issues !== undefined)\n    return { ok: false, issues: result.issues.map((i) => i.message) };\n  return { ok: true, value: result.value };\n}\n\n/** Parses an attribute value (`null`: absent) per the builder table; undefined means missing. */\nexport function parseAttribute(def: Prop<unknown>, raw: string | null): Checked | undefined {\n  if (def.kind === 'boolean') return { ok: true, value: raw !== null };\n  if (raw === null) return undefined;\n  if (def.kind === 'number') {\n    const n = raw.trim() === '' ? Number.NaN : Number(raw);\n    return Number.isNaN(n)\n      ? { ok: false, issues: [`\"${raw}\" is not a number`] }\n      : { ok: true, value: n };\n  }\n  if (def.kind === 'json') {\n    try {\n      return { ok: true, value: JSON.parse(raw) as unknown };\n    } catch {\n      return { ok: false, issues: ['the attribute is not valid JSON'] };\n    }\n  }\n  return { ok: true, value: raw };\n}\n\n/** Logs an invalid value; the caller then treats the prop as missing. */\nexport function reportInvalid(tag: string, name: string, from: string, issues: readonly string[]) {\n  console.error(message(21, tag, name, from, issues.join('; ')));\n}\n\n/**\n * An attribute's value for prop `name` (view/05-element.md \"When props are validated\"):\n * parsed per the builder and always validated; invalid or absent values are missing.\n */\nexport function attributeValue(\n  tag: string,\n  name: string,\n  def: Prop<unknown> | undefined,\n  attr: string,\n  raw: string | null,\n): unknown {\n  const parsed = def === undefined ? undefined : parseAttribute(def, raw);\n  if (def === undefined || parsed === undefined) return undefined;\n  const checked = parsed.ok ? checkValue(tag, name, def, parsed.value) : parsed;\n  if (checked.ok) return checked.value;\n  reportInvalid(tag, name, `the attribute ${attr}`, checked.issues);\n  return undefined;\n}\n\n/**\n * A property set's (or seed's) value for prop `name`: validated in development only, where an\n * invalid value is missing and a schema that transforms warns. Production keeps the input\n * without calling this (propFeature, element.ts: gyral-c5d.14).\n */\nexport function propertyValue(\n  tag: string,\n  name: string,\n  def: Prop<unknown> | undefined,\n  value: unknown,\n  from = 'a property',\n): unknown {\n  if (!DEV || value === undefined || def === undefined) return value;\n  const checked = checkValue(tag, name, def, value);\n  if (!checked.ok) {\n    reportInvalid(tag, name, from, checked.issues);\n    return undefined;\n  }\n  if (!sameData(checked.value, value)) {\n    console.warn(\n      `<${tag}> prop \"${name}\": its schema transformed the value from ${from}. Production ` +\n        \"doesn't run schemas on property sets; validate, don't transform.\",\n    );\n  }\n  return value;\n}\n\n/** Structural equality for plain data (arrays, plain objects), `Object.is` for the rest. */\nexport function sameData(a: unknown, b: unknown): boolean {\n  if (Object.is(a, b)) return true;\n  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;\n  if (Array.isArray(a)) {\n    return Array.isArray(b) && a.length === b.length && a.every((x, i) => sameData(x, b[i]));\n  }\n  if (\n    Object.getPrototypeOf(a) !== Object.prototype ||\n    Object.getPrototypeOf(b) !== Object.prototype\n  ) {\n    return false;\n  }\n  const ka = Object.keys(a);\n  return (\n    ka.length === Object.keys(b).length && ka.every((k) => sameData((a as Bag)[k], (b as Bag)[k]))\n  );\n}\n\n/** The declared props as components see them: `default` fills missing values. */\nexport function readProps(values: Bag, table: PropTable): Bag {\n  const out: Record<string, unknown> = {};\n  for (const [name, def] of Object.entries(table)) {\n    const value = values[name];\n    out[name] = value === undefined ? def.default : value;\n  }\n  return out;\n}\n\n/** Required props that are still missing (ADR 0007 addendum). */\nexport function missingRequired(values: Bag, table: PropTable): string[] {\n  return Object.keys(table).filter(\n    (name) => table[name]?.required === true && values[name] === undefined,\n  );\n}\n\n/** Warns about required props that are still missing, at first render. */\nexport function warnMissing(tag: string, values: Bag, table: PropTable): void {\n  const missing = missingRequired(values, table);\n  if (missing.length > 0) {\n    console.warn(message(22, tag, missing.join(', ')));\n  }\n}\n\n/**\n * Declared props that collide with a built-in element property (`hidden`, `title`, `id`, …):\n * the accessor replaces the built-in, so setting the prop silently changes what the platform\n * does with it (gyral-czi.33).\n */\nexport function shadowedBuiltins(names: readonly string[]): string[] {\n  if (typeof HTMLElement === 'undefined') return [];\n  return names.filter((name) => name in HTMLElement.prototype);\n}\n\n/** define(): a prop named like a built-in property is an error in development, else a warning. */\nexport function checkShadowed(tag: string, names: readonly string[]): void {\n  const shadowed = shadowedBuiltins(names);\n  if (shadowed.length === 0) return;\n  const text = message(23, tag, shadowed.join(', '));\n  if (DEV) throw new TypeError(text);\n  console.warn(text);\n}\n\n/**\n * What the element uses, registered by the prop builders (features.ts). Property sets and seeds\n * go through `propertyValue` in development only: production keeps the value as given, so the\n * property path's schema and guard handling stay out of production bundles (gyral-c5d.14).\n */\nexport const propFeature = {\n  attributeOf,\n  attributeValue,\n  propertyValue: DEV ? propertyValue : undefined,\n  warnMissing,\n  readProps,\n  checkShadowed,\n};\n\nexport type PropFeature = typeof propFeature;\n"]}

package/dist/retry.d.ts

@@ -0,0 +1,15 @@
+import type { Driver, RetryPolicy } from './command.js';
+/**
+ * The same driver (same name, so substitution by name still works), with `run` retried when it
+ * rejects: up to `policy.times` more attempts, after `delayMs` (doubling from it with
+ * `backoff: 'exponential'`; a random part of it with `jitter`), and only for failures
+ * `retryIf` accepts. An abort (the command switched away, the component disconnected) ends it
+ * at once and is never retried. Wrap where the driver is chosen: app setup, a component's
+ * `drivers`, or a test fake.
+ *
+ *   const api = retry(makeHttpDriver({ baseUrl: '/api', timeoutMs: 8000 }), {
+ *     times: 3, delayMs: 300, backoff: 'exponential', jitter: true, retryIf: retryableHttpError,
+ *   });
+ *   const feed = retry(subscription('feed', connect), { times: Infinity, delayMs: 1000 });
+ */
+export declare function retry<I, O, E>(driver: Driver<I, O, E>, policy: RetryPolicy<E>): Driver<I, O, E>;

package/dist/retry.js

@@ -0,0 +1,48 @@
+/** Waits `ms`, or rejects with the abort reason as soon as `signal` aborts. */
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    const stop = () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+        signal.removeEventListener('abort', stop);
+        resolve();
+    }, ms);
+    signal.addEventListener('abort', stop, { once: true });
+});
+/**
+ * The same driver (same name, so substitution by name still works), with `run` retried when it
+ * rejects: up to `policy.times` more attempts, after `delayMs` (doubling from it with
+ * `backoff: 'exponential'`; a random part of it with `jitter`), and only for failures
+ * `retryIf` accepts. An abort (the command switched away, the component disconnected) ends it
+ * at once and is never retried. Wrap where the driver is chosen: app setup, a component's
+ * `drivers`, or a test fake.
+ *
+ *   const api = retry(makeHttpDriver({ baseUrl: '/api', timeoutMs: 8000 }), {
+ *     times: 3, delayMs: 300, backoff: 'exponential', jitter: true, retryIf: retryableHttpError,
+ *   });
+ *   const feed = retry(subscription('feed', connect), { times: Infinity, delayMs: 1000 });
+ */
+export function retry(driver, policy) {
+    const { times, delayMs: base = 0, backoff, jitter, retryIf } = policy;
+    return {
+        ...driver,
+        run: async (input, ctx) => {
+            for (let attempt = 0;; attempt += 1) {
+                try {
+                    return await driver.run(input, ctx);
+                }
+                catch (cause) {
+                    if (ctx.signal.aborted || attempt >= times)
+                        throw cause;
+                    // Sound: without `toError` the driver's error type is what it throws.
+                    if (retryIf?.(driver.toError?.(cause) ?? cause) === false)
+                        throw cause;
+                    const delay = backoff === 'exponential' ? base * 2 ** attempt : base;
+                    await sleep(jitter === true ? Math.random() * delay : delay, ctx.signal);
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAIA,+EAA+E;AAC/E,MAAM,KAAK,GAAG,CAAC,EAAU,EAAE,MAAmB,EAAiB,EAAE,CAC/D,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;IAC9B,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,MAAM,CAAC,MAAM,CAAC,MAAe,CAAC,CAAC;IACjC,CAAC,CAAC;IACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC5B,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC1C,OAAO,EAAE,CAAC;IACZ,CAAC,EAAE,EAAE,CAAC,CAAC;IACP,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AACzD,CAAC,CAAC,CAAC;AAEL;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,KAAK,CAAU,MAAuB,EAAE,MAAsB;IAC5E,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IACtE,OAAO;QACL,GAAG,MAAM;QACT,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACxB,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,IAAI,CAAC,EAAE,CAAC;gBACrC,IAAI,CAAC;oBACH,OAAO,MAAM,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;gBACtC,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,OAAO,IAAI,KAAK;wBAAE,MAAM,KAAK,CAAC;oBACxD,sEAAsE;oBACtE,IAAI,OAAO,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,IAAK,KAAW,CAAC,KAAK,KAAK;wBAAE,MAAM,KAAK,CAAC;oBAC9E,MAAM,KAAK,GAAG,OAAO,KAAK,aAAa,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;oBACrE,MAAM,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;gBAC3E,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["// Retries as a driver wrapper (ADR 0022): the interpreter runs a driver once, and apps that\n// never call `retry` don't bundle its delays. A standalone module, like subscription.ts.\nimport type { Driver, RetryPolicy } from './command.js';\n\n/** Waits `ms`, or rejects with the abort reason as soon as `signal` aborts. */\nconst sleep = (ms: number, signal: AbortSignal): Promise<void> =>\n  new Promise((resolve, reject) => {\n    const stop = (): void => {\n      clearTimeout(timer);\n      reject(signal.reason as Error);\n    };\n    const timer = setTimeout(() => {\n      signal.removeEventListener('abort', stop);\n      resolve();\n    }, ms);\n    signal.addEventListener('abort', stop, { once: true });\n  });\n\n/**\n * The same driver (same name, so substitution by name still works), with `run` retried when it\n * rejects: up to `policy.times` more attempts, after `delayMs` (doubling from it with\n * `backoff: 'exponential'`; a random part of it with `jitter`), and only for failures\n * `retryIf` accepts. An abort (the command switched away, the component disconnected) ends it\n * at once and is never retried. Wrap where the driver is chosen: app setup, a component's\n * `drivers`, or a test fake.\n *\n *   const api = retry(makeHttpDriver({ baseUrl: '/api', timeoutMs: 8000 }), {\n *     times: 3, delayMs: 300, backoff: 'exponential', jitter: true, retryIf: retryableHttpError,\n *   });\n *   const feed = retry(subscription('feed', connect), { times: Infinity, delayMs: 1000 });\n */\nexport function retry<I, O, E>(driver: Driver<I, O, E>, policy: RetryPolicy<E>): Driver<I, O, E> {\n  const { times, delayMs: base = 0, backoff, jitter, retryIf } = policy;\n  return {\n    ...driver,\n    run: async (input, ctx) => {\n      for (let attempt = 0; ; attempt += 1) {\n        try {\n          return await driver.run(input, ctx);\n        } catch (cause) {\n          if (ctx.signal.aborted || attempt >= times) throw cause;\n          // Sound: without `toError` the driver's error type is what it throws.\n          if (retryIf?.(driver.toError?.(cause) ?? (cause as E)) === false) throw cause;\n          const delay = backoff === 'exponential' ? base * 2 ** attempt : base;\n          await sleep(jitter === true ? Math.random() * delay : delay, ctx.signal);\n        }\n      }\n    },\n  };\n}\n"]}

package/dist/scheduler.d.ts

@@ -0,0 +1,43 @@
+/** One host as the scheduler sees it. define() creates one per element. */
+export interface HostTask {
+    /** The component's tag, for errors and the loop guard. */
+    readonly tag: string;
+    /** Gyral host ancestors in the composed tree, recorded when the host connects. */
+    depth: number;
+    /** `PropsChanged` (when props changed), then the view and its commit. May throw. */
+    readonly render: () => void;
+}
+/** Post-render phases, run in this order once per pass (04 "Post-render queue"). */
+export declare const POST_FOCUS = 0;
+export declare const POST_STATES = 1;
+export declare const POST_HYDRATED = 2;
+export declare const POST_INIT = 3;
+/** A message reached a host or a store (04 "`settled()`": messages restart the quiet window). */
+export declare function noteActivity(): void;
+/** How much activity (messages, marks) the page has seen; only differences matter. */
+export declare const activityCount: () => number;
+/**
+ * True when no host is dirty (in either lane), no flush or transition update is pending and
+ * nothing is deferred.
+ */
+export declare const isQuiet: () => boolean;
+/** Resolves at the end of the flush that leaves the scheduler quiet. */
+export declare function whenQuiet(): Promise<void>;
+/**
+ * Marks `task` for the next flush: the microtask one, or with `onFrame` the next animation
+ * frame's (04 "Frame lane"; the microtask one when the build left the frame lane out). Marking
+ * an already-dirty host does nothing; a microtask mark moves a host waiting for the frame into
+ * the microtask flush.
+ */
+export declare function markDirty(task: HostTask, onFrame?: boolean): void;
+/** Queues post-render work for the current (or next) flush. */
+export declare function afterRender(phaseOf: number, run: () => void): void;
+/** A message asked for a view transition: the pending flush runs inside one (04). */
+export declare function requestTransition(): void;
+/** Runs `fn` in a microtask that settled() waits for (outputs sent up to a parent). */
+export declare function defer(fn: () => void): void;
+/**
+ * Counts `work` (code loading with import(), whose continuation connects hosts) as pending
+ * until it settles, so settled() waits for it. `work` must not reject.
+ */
+export declare function hold(work: Promise<void>): void;

package/dist/scheduler.js

@@ -0,0 +1,212 @@
+// The global scheduler (docs/design-docs/view/04-scheduler.md). Every host's render goes
+// through it: reducers run at once, the render waits for one microtask flush shared by the
+// whole page. A flush renders dirty hosts parents first (smallest depth, then marking order),
+// then their element hooks (children first, view/02 "Commit order"), then runs the post-render queue (focus, custom states, `Hydrated`, deferred init commands),
+// and loops until nothing is dirty. Messages a spec lists in `renderOnFrame` mark their host in
+// the frame lane instead: it renders in the next animation frame (04 "Frame lane",
+// frame-lane.ts). The frame lane and view transitions come through `#spec-features`, present
+// unless a compiled build found no module naming them (gyral-c5d.12). It lives outside view/
+// (view/ never imports it) and drives the renderer through view/index.ts.
+import { fail } from './errors.js';
+import { frameLane, viewTransitions } from '#spec-features';
+import { DEV, flushHooks, message, renderBatch } from './view/index.js';
+/** Post-render phases, run in this order once per pass (04 "Post-render queue"). */
+export const POST_FOCUS = 0;
+export const POST_STATES = 1;
+export const POST_HYDRATED = 2;
+export const POST_INIT = 3;
+/** Loop guard (04 "Loop guard"): renders of one host, and passes, in one flush. */
+const MAX_RENDERS = 10;
+const MAX_PASSES = 100;
+const IDLE = 0;
+const SCHEDULED = 1;
+const TRANSITION = 2;
+const FLUSHING = 3;
+const dirty = new Set();
+let post = [];
+let phase = IDLE;
+let transitionWanted = false;
+/** Deferred callbacks (outputs to parents) and held loads still pending; settled() waits. */
+let deferred = 0;
+let quiet = null;
+/** Messages delivered and hosts marked so far; settled() restarts its quiet window on a change. */
+let activity = 0;
+/** A message reached a host or a store (04 "`settled()`": messages restart the quiet window). */
+export function noteActivity() {
+    activity += 1;
+}
+/** How much activity (messages, marks) the page has seen; only differences matter. */
+export const activityCount = () => activity;
+/**
+ * True when no host is dirty (in either lane), no flush or transition update is pending and
+ * nothing is deferred.
+ */
+export const isQuiet = () => phase === IDLE && dirty.size === 0 && frameLane?.pending() !== true && deferred === 0;
+/** Resolves at the end of the flush that leaves the scheduler quiet. */
+export function whenQuiet() {
+    if (isQuiet())
+        return Promise.resolve();
+    if (quiet === null) {
+        quiet = Promise.withResolvers();
+    }
+    return quiet.promise;
+}
+function schedule() {
+    if (phase !== IDLE)
+        return;
+    phase = SCHEDULED;
+    queueMicrotask(start);
+}
+/**
+ * Marks `task` for the next flush: the microtask one, or with `onFrame` the next animation
+ * frame's (04 "Frame lane"; the microtask one when the build left the frame lane out). Marking
+ * an already-dirty host does nothing; a microtask mark moves a host waiting for the frame into
+ * the microtask flush.
+ */
+export function markDirty(task, onFrame = false) {
+    activity += 1;
+    if (dirty.has(task))
+        return;
+    if (onFrame && frameLane !== undefined) {
+        frameLane.add(task, markDirty);
+        return;
+    }
+    frameLane?.drop(task);
+    dirty.add(task);
+    schedule();
+}
+/** Queues post-render work for the current (or next) flush. */
+export function afterRender(phaseOf, run) {
+    post.push({ phase: phaseOf, run });
+    schedule();
+}
+/** A message asked for a view transition: the pending flush runs inside one (04). */
+export function requestTransition() {
+    if (phase === IDLE || phase === SCHEDULED)
+        transitionWanted = true;
+}
+/** Runs `fn` in a microtask that settled() waits for (outputs sent up to a parent). */
+export function defer(fn) {
+    deferred += 1;
+    queueMicrotask(() => {
+        try {
+            fn();
+        }
+        catch (error) {
+            fail(error, 'command', message(30));
+        }
+        finally {
+            deferred -= 1;
+            settle();
+        }
+    });
+}
+/**
+ * Counts `work` (code loading with import(), whose continuation connects hosts) as pending
+ * until it settles, so settled() waits for it. `work` must not reject.
+ */
+export function hold(work) {
+    deferred += 1;
+    void work.finally(() => {
+        deferred -= 1;
+        settle();
+    });
+}
+function start() {
+    if (transitionWanted) {
+        phase = TRANSITION;
+        if (viewTransitions?.(flush) === true)
+            return;
+    }
+    flush();
+}
+/** The dirty host with the smallest depth; ties go to the one marked first. */
+function next() {
+    let best;
+    for (const task of dirty)
+        if (best === undefined || task.depth < best.depth)
+            best = task;
+    return best;
+}
+function renderAll(counts) {
+    while (dirty.size > 0) {
+        const task = next();
+        dirty.delete(task);
+        const renders = (counts.get(task) ?? 0) + 1;
+        counts.set(task, renders);
+        if (renders > MAX_RENDERS)
+            throw loopError(counts);
+        try {
+            task.render();
+        }
+        catch (error) {
+            fail(error, 'view', message(31, task.tag), { tag: task.tag });
+        }
+    }
+}
+function runPost() {
+    const tasks = post.sort((a, b) => a.phase - b.phase); // stable: queue order within a phase
+    post = [];
+    for (const task of tasks) {
+        try {
+            task.run();
+        }
+        catch (error) {
+            fail(error, 'view', message(32));
+        }
+    }
+}
+function loopError(counts) {
+    const tags = [...new Set([...counts.keys()].map((t) => `<${t.tag}>`))].join(', ');
+    return new Error(message(33, tags));
+}
+function flush() {
+    phase = FLUSHING;
+    const counts = new Map();
+    let failure;
+    try {
+        renderBatch(() => {
+            for (let pass = 1;; pass++) {
+                renderAll(counts);
+                flushHooks(); // every dirty host rendered: element hooks run, children first
+                // Client calls can deliver intents: commit their new state before focus/other work.
+                if (dirty.size === 0 && post.length > 0)
+                    runPost();
+                if (dirty.size === 0 && post.length === 0)
+                    return;
+                if (pass >= MAX_PASSES)
+                    throw loopError(counts);
+            }
+        });
+    }
+    catch (error) {
+        dirty.clear();
+        post = [];
+        failure = error instanceof Error ? error : new Error(String(error));
+    }
+    phase = IDLE;
+    transitionWanted = false;
+    if (failure === undefined) {
+        settle();
+    }
+    else if (!DEV) {
+        fail(failure, 'view', failure.message); // production: report and drop the rest, so the page doesn't freeze
+        settle();
+    }
+    else if (quiet !== null) {
+        const waiting = quiet;
+        quiet = null;
+        waiting.reject(failure);
+    }
+    else {
+        throw failure;
+    }
+}
+function settle() {
+    if (quiet === null || !isQuiet())
+        return;
+    const waiting = quiet;
+    quiet = null;
+    waiting.resolve();
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,2FAA2F;AAC3F,8FAA8F;AAC9F,iKAAiK;AACjK,gGAAgG;AAChG,mFAAmF;AACnF,6FAA6F;AAC7F,6FAA6F;AAC7F,0EAA0E;AAC1E,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAYxE,oFAAoF;AACpF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAC5B,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAC7B,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC;AAC/B,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC;AAO3B,mFAAmF;AACnF,MAAM,WAAW,GAAG,EAAE,CAAC;AACvB,MAAM,UAAU,GAAG,GAAG,CAAC;AAEvB,MAAM,IAAI,GAAG,CAAC,CAAC;AACf,MAAM,SAAS,GAAG,CAAC,CAAC;AACpB,MAAM,UAAU,GAAG,CAAC,CAAC;AACrB,MAAM,QAAQ,GAAG,CAAC,CAAC;AAEnB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAY,CAAC;AAClC,IAAI,IAAI,GAAe,EAAE,CAAC;AAC1B,IAAI,KAAK,GAAG,IAAI,CAAC;AACjB,IAAI,gBAAgB,GAAG,KAAK,CAAC;AAC7B,6FAA6F;AAC7F,IAAI,QAAQ,GAAG,CAAC,CAAC;AACjB,IAAI,KAAK,GACP,IAAI,CAAC;AACP,mGAAmG;AACnG,IAAI,QAAQ,GAAG,CAAC,CAAC;AAEjB,iGAAiG;AACjG,MAAM,UAAU,YAAY;IAC1B,QAAQ,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,sFAAsF;AACtF,MAAM,CAAC,MAAM,aAAa,GAAG,GAAW,EAAE,CAAC,QAAQ,CAAC;AAEpD;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,GAAY,EAAE,CACnC,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,SAAS,EAAE,OAAO,EAAE,KAAK,IAAI,IAAI,QAAQ,KAAK,CAAC,CAAC;AAExF,wEAAwE;AACxE,MAAM,UAAU,SAAS;IACvB,IAAI,OAAO,EAAE;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IACxC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,KAAK,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,KAAK,CAAC,OAAO,CAAC;AACvB,CAAC;AAED,SAAS,QAAQ;IACf,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO;IAC3B,KAAK,GAAG,SAAS,CAAC;IAClB,cAAc,CAAC,KAAK,CAAC,CAAC;AACxB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,IAAc,EAAE,OAAO,GAAG,KAAK;IACvD,QAAQ,IAAI,CAAC,CAAC;IACd,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO;IAC5B,IAAI,OAAO,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QACvC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC/B,OAAO;IACT,CAAC;IACD,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChB,QAAQ,EAAE,CAAC;AACb,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,GAAe;IAC1D,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;IACnC,QAAQ,EAAE,CAAC;AACb,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,iBAAiB;IAC/B,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,gBAAgB,GAAG,IAAI,CAAC;AACrE,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,KAAK,CAAC,EAAc;IAClC,QAAQ,IAAI,CAAC,CAAC;IACd,cAAc,CAAC,GAAG,EAAE;QAClB,IAAI,CAAC;YACH,EAAE,EAAE,CAAC;QACP,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;QACtC,CAAC;gBAAS,CAAC;YACT,QAAQ,IAAI,CAAC,CAAC;YACd,MAAM,EAAE,CAAC;QACX,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,IAAmB;IACtC,QAAQ,IAAI,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE;QACrB,QAAQ,IAAI,CAAC,CAAC;QACd,MAAM,EAAE,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,KAAK;IACZ,IAAI,gBAAgB,EAAE,CAAC;QACrB,KAAK,GAAG,UAAU,CAAC;QACnB,IAAI,eAAe,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI;YAAE,OAAO;IAChD,CAAC;IACD,KAAK,EAAE,CAAC;AACV,CAAC;AAED,+EAA+E;AAC/E,SAAS,IAAI;IACX,IAAI,IAA0B,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK;YAAE,IAAI,GAAG,IAAI,CAAC;IACzF,OAAO,IAAgB,CAAC;AAC1B,CAAC;AAED,SAAS,SAAS,CAAC,MAA6B;IAC9C,OAAO,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC;QACpB,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAC5C,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC1B,IAAI,OAAO,GAAG,WAAW;YAAE,MAAM,SAAS,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,OAAO;IACd,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,qCAAqC;IAC3F,IAAI,GAAG,EAAE,CAAC;IACV,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,MAA6B;IAC9C,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClF,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,KAAK;IACZ,KAAK,GAAG,QAAQ,CAAC;IACjB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC3C,IAAI,OAA0B,CAAC;IAC/B,IAAI,CAAC;QACH,WAAW,CAAC,GAAG,EAAE;YACf,KAAK,IAAI,IAAI,GAAG,CAAC,GAAI,IAAI,EAAE,EAAE,CAAC;gBAC5B,SAAS,CAAC,MAAM,CAAC,CAAC;gBAClB,UAAU,EAAE,CAAC,CAAC,+DAA+D;gBAC7E,oFAAoF;gBACpF,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;oBAAE,OAAO,EAAE,CAAC;gBACnD,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;oBAAE,OAAO;gBAClD,IAAI,IAAI,IAAI,UAAU;oBAAE,MAAM,SAAS,CAAC,MAAM,CAAC,CAAC;YAClD,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,IAAI,GAAG,EAAE,CAAC;QACV,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACtE,CAAC;IACD,KAAK,GAAG,IAAI,CAAC;IACb,gBAAgB,GAAG,KAAK,CAAC;IACzB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,EAAE,CAAC;IACX,CAAC;SAAM,IAAI,CAAC,GAAG,EAAE,CAAC;QAChB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,mEAAmE;QAC3G,MAAM,EAAE,CAAC;IACX,CAAC;SAAM,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,KAAK,CAAC;QACtB,KAAK,GAAG,IAAI,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;SAAM,CAAC;QACN,MAAM,OAAO,CAAC;IAChB,CAAC;AACH,CAAC;AAED,SAAS,MAAM;IACb,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE;QAAE,OAAO;IACzC,MAAM,OAAO,GAAG,KAAK,CAAC;IACtB,KAAK,GAAG,IAAI,CAAC;IACb,OAAO,CAAC,OAAO,EAAE,CAAC;AACpB,CAAC","sourcesContent":["// The global scheduler (docs/design-docs/view/04-scheduler.md). Every host's render goes\n// through it: reducers run at once, the render waits for one microtask flush shared by the\n// whole page. A flush renders dirty hosts parents first (smallest depth, then marking order),\n// then their element hooks (children first, view/02 \"Commit order\"), then runs the post-render queue (focus, custom states, `Hydrated`, deferred init commands),\n// and loops until nothing is dirty. Messages a spec lists in `renderOnFrame` mark their host in\n// the frame lane instead: it renders in the next animation frame (04 \"Frame lane\",\n// frame-lane.ts). The frame lane and view transitions come through `#spec-features`, present\n// unless a compiled build found no module naming them (gyral-c5d.12). It lives outside view/\n// (view/ never imports it) and drives the renderer through view/index.ts.\nimport { fail } from './errors.js';\nimport { frameLane, viewTransitions } from '#spec-features';\nimport { DEV, flushHooks, message, renderBatch } from './view/index.js';\n\n/** One host as the scheduler sees it. define() creates one per element. */\nexport interface HostTask {\n  /** The component's tag, for errors and the loop guard. */\n  readonly tag: string;\n  /** Gyral host ancestors in the composed tree, recorded when the host connects. */\n  depth: number;\n  /** `PropsChanged` (when props changed), then the view and its commit. May throw. */\n  readonly render: () => void;\n}\n\n/** Post-render phases, run in this order once per pass (04 \"Post-render queue\"). */\nexport const POST_FOCUS = 0;\nexport const POST_STATES = 1;\nexport const POST_HYDRATED = 2;\nexport const POST_INIT = 3;\n\ninterface PostTask {\n  readonly phase: number;\n  readonly run: () => void;\n}\n\n/** Loop guard (04 \"Loop guard\"): renders of one host, and passes, in one flush. */\nconst MAX_RENDERS = 10;\nconst MAX_PASSES = 100;\n\nconst IDLE = 0;\nconst SCHEDULED = 1;\nconst TRANSITION = 2;\nconst FLUSHING = 3;\n\nconst dirty = new Set<HostTask>();\nlet post: PostTask[] = [];\nlet phase = IDLE;\nlet transitionWanted = false;\n/** Deferred callbacks (outputs to parents) and held loads still pending; settled() waits. */\nlet deferred = 0;\nlet quiet: { promise: Promise<void>; resolve: () => void; reject: (e: unknown) => void } | null =\n  null;\n/** Messages delivered and hosts marked so far; settled() restarts its quiet window on a change. */\nlet activity = 0;\n\n/** A message reached a host or a store (04 \"`settled()`\": messages restart the quiet window). */\nexport function noteActivity(): void {\n  activity += 1;\n}\n\n/** How much activity (messages, marks) the page has seen; only differences matter. */\nexport const activityCount = (): number => activity;\n\n/**\n * True when no host is dirty (in either lane), no flush or transition update is pending and\n * nothing is deferred.\n */\nexport const isQuiet = (): boolean =>\n  phase === IDLE && dirty.size === 0 && frameLane?.pending() !== true && deferred === 0;\n\n/** Resolves at the end of the flush that leaves the scheduler quiet. */\nexport function whenQuiet(): Promise<void> {\n  if (isQuiet()) return Promise.resolve();\n  if (quiet === null) {\n    quiet = Promise.withResolvers();\n  }\n  return quiet.promise;\n}\n\nfunction schedule(): void {\n  if (phase !== IDLE) return;\n  phase = SCHEDULED;\n  queueMicrotask(start);\n}\n\n/**\n * Marks `task` for the next flush: the microtask one, or with `onFrame` the next animation\n * frame's (04 \"Frame lane\"; the microtask one when the build left the frame lane out). Marking\n * an already-dirty host does nothing; a microtask mark moves a host waiting for the frame into\n * the microtask flush.\n */\nexport function markDirty(task: HostTask, onFrame = false): void {\n  activity += 1;\n  if (dirty.has(task)) return;\n  if (onFrame && frameLane !== undefined) {\n    frameLane.add(task, markDirty);\n    return;\n  }\n  frameLane?.drop(task);\n  dirty.add(task);\n  schedule();\n}\n\n/** Queues post-render work for the current (or next) flush. */\nexport function afterRender(phaseOf: number, run: () => void): void {\n  post.push({ phase: phaseOf, run });\n  schedule();\n}\n\n/** A message asked for a view transition: the pending flush runs inside one (04). */\nexport function requestTransition(): void {\n  if (phase === IDLE || phase === SCHEDULED) transitionWanted = true;\n}\n\n/** Runs `fn` in a microtask that settled() waits for (outputs sent up to a parent). */\nexport function defer(fn: () => void): void {\n  deferred += 1;\n  queueMicrotask(() => {\n    try {\n      fn();\n    } catch (error) {\n      fail(error, 'command', message(30));\n    } finally {\n      deferred -= 1;\n      settle();\n    }\n  });\n}\n\n/**\n * Counts `work` (code loading with import(), whose continuation connects hosts) as pending\n * until it settles, so settled() waits for it. `work` must not reject.\n */\nexport function hold(work: Promise<void>): void {\n  deferred += 1;\n  void work.finally(() => {\n    deferred -= 1;\n    settle();\n  });\n}\n\nfunction start(): void {\n  if (transitionWanted) {\n    phase = TRANSITION;\n    if (viewTransitions?.(flush) === true) return;\n  }\n  flush();\n}\n\n/** The dirty host with the smallest depth; ties go to the one marked first. */\nfunction next(): HostTask {\n  let best: HostTask | undefined;\n  for (const task of dirty) if (best === undefined || task.depth < best.depth) best = task;\n  return best as HostTask;\n}\n\nfunction renderAll(counts: Map<HostTask, number>): void {\n  while (dirty.size > 0) {\n    const task = next();\n    dirty.delete(task);\n    const renders = (counts.get(task) ?? 0) + 1;\n    counts.set(task, renders);\n    if (renders > MAX_RENDERS) throw loopError(counts);\n    try {\n      task.render();\n    } catch (error) {\n      fail(error, 'view', message(31, task.tag), { tag: task.tag });\n    }\n  }\n}\n\nfunction runPost(): void {\n  const tasks = post.sort((a, b) => a.phase - b.phase); // stable: queue order within a phase\n  post = [];\n  for (const task of tasks) {\n    try {\n      task.run();\n    } catch (error) {\n      fail(error, 'view', message(32));\n    }\n  }\n}\n\nfunction loopError(counts: Map<HostTask, number>): Error {\n  const tags = [...new Set([...counts.keys()].map((t) => `<${t.tag}>`))].join(', ');\n  return new Error(message(33, tags));\n}\n\nfunction flush(): void {\n  phase = FLUSHING;\n  const counts = new Map<HostTask, number>();\n  let failure: Error | undefined;\n  try {\n    renderBatch(() => {\n      for (let pass = 1; ; pass++) {\n        renderAll(counts);\n        flushHooks(); // every dirty host rendered: element hooks run, children first\n        // Client calls can deliver intents: commit their new state before focus/other work.\n        if (dirty.size === 0 && post.length > 0) runPost();\n        if (dirty.size === 0 && post.length === 0) return;\n        if (pass >= MAX_PASSES) throw loopError(counts);\n      }\n    });\n  } catch (error) {\n    dirty.clear();\n    post = [];\n    failure = error instanceof Error ? error : new Error(String(error));\n  }\n  phase = IDLE;\n  transitionWanted = false;\n  if (failure === undefined) {\n    settle();\n  } else if (!DEV) {\n    fail(failure, 'view', failure.message); // production: report and drop the rest, so the page doesn't freeze\n    settle();\n  } else if (quiet !== null) {\n    const waiting = quiet;\n    quiet = null;\n    waiting.reject(failure);\n  } else {\n    throw failure;\n  }\n}\n\nfunction settle(): void {\n  if (quiet === null || !isQuiet()) return;\n  const waiting = quiet;\n  quiet = null;\n  waiting.resolve();\n}\n"]}

package/dist/script-json.d.ts

@@ -0,0 +1,2 @@
+/** JSON for an inline `<script type="application/json">`: `</script>` and friends escaped. */
+export declare function scriptSafeJson(value: unknown): string;

package/dist/script-json.js

@@ -0,0 +1,13 @@
+// JSON safe to inline in a <script> element. Its own module: head.ts (the head model) and the
+// store seeds both use it, and keeping it out of store-scope.ts stops a bundler from turning
+// the store registry into a shared chunk every page loads (gyral-dyn.35).
+/** JSON for an inline `<script type="application/json">`: `</script>` and friends escaped. */
+export function scriptSafeJson(value) {
+    return JSON.stringify(value)
+        .replaceAll('<', '\\u003c')
+        .replaceAll('>', '\\u003e')
+        .replaceAll('&', '\\u0026')
+        .replaceAll('
', '\\u2028')
+        .replaceAll('
', '\\u2029');
+}
+//# sourceMappingURL=script-json.js.map

package/dist/script-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"script-json.js","sourceRoot":"","sources":["../src/script-json.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,6FAA6F;AAC7F,0EAA0E;AAE1E,8FAA8F;AAC9F,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;SACzB,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC;SAC1B,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC;SAC1B,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC;SAC1B,UAAU,CAAC;CACf,EAAE,SAAS,CAAC;SACR,UAAU,CAAC;CACf,EAAE,SAAS,CAAC,CAAC;AACd,CAAC","sourcesContent":["// JSON safe to inline in a <script> element. Its own module: head.ts (the head model) and the\n// store seeds both use it, and keeping it out of store-scope.ts stops a bundler from turning\n// the store registry into a shared chunk every page loads (gyral-dyn.35).\n\n/** JSON for an inline `<script type=\"application/json\">`: `</script>` and friends escaped. */\nexport function scriptSafeJson(value: unknown): string {\n  return JSON.stringify(value)\n    .replaceAll('<', '\\\\u003c')\n    .replaceAll('>', '\\\\u003e')\n    .replaceAll('&', '\\\\u0026')\n    .replaceAll('
', '\\\\u2028')\n    .replaceAll('
', '\\\\u2029');\n}\n"]}

package/dist/server-component.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentSpec, Tagged } from './types.js';
+import { type ServerComponent } from './view/index.js';
+/** The server registry entry for `spec`. */
+export declare function serverComponent<S, M extends Tagged, P>(tag: string, spec: ComponentSpec<S, M, P>): ServerComponent;
+/**
+ * Registers every spec define() recorded outside the browser (and not registered yet) in
+ * view/'s server registry. `@gyral/core/internal/server` calls it before each render; client code never
+ * imports this module.
+ */
+export declare function registerRecordedSpecs(): void;