@gyral/core 0.2.0 → 0.3.0

package/dist/stores-provider.js

@@ -1,57 +1,23 @@
-// `<gyral-stores>` as a real element for server rendering (gyral-czi.20, ADR 0013 addendum).
-// On the client a provider is a plain element (scopeFor walks the DOM). On the server it must
-// be a registered element: components find it through Lit's SSR event path, and its instances'
-// states are written to `data-gyral-stores` for the client to restore.
-import { css, html, isServer, LitElement } from 'lit';
+// `<gyral-stores>` on the server (ADR 0013, view/06-server.md "Components"). In the browser a
+// provider is a plain element: scopeFor() walks the DOM to it. On the server it is written as a
+// plain element too, and the renderer gives its subtree the provider's registry (components'
+// `ctx.read` resolves there) and writes its `data-gyral-stores` seed: the states of the
+// instances passed in `.instances`. Stores not listed start from `init` on both sides.
 import { warnJsonHazard } from './json-safety.js';
-import { providerScope, STORE_SEED_ATTRIBUTE, STORES_ELEMENT, STORES_REQUEST, } from './store-scope.js';
-const onServer = isServer;
-/** Server-only element: renders `<slot>` in Declarative Shadow DOM, so children show as-is. */
-class GyralStores extends LitElement {
-    static { this.styles = css `
-    :host {
-      display: contents;
-    }
-  `; }
-    #instances;
-    /** This subtree's store instances; stores not listed start from their seed or `init`. */
-    get instances() {
-        return this.#instances;
-    }
-    set instances(value) {
-        this.#instances = value;
-        // Written before the attributes render; the client restores it (providerScope()).
-        if (value !== undefined && value.length > 0) {
-            const seed = Object.fromEntries(value.map((i) => [i.store.name, i.state]));
-            for (const [name, state] of Object.entries(seed)) {
-                warnJsonHazard(`store "${name}" in <${STORES_ELEMENT}>`, state, 'state');
-            }
-            this.setAttribute(STORE_SEED_ATTRIBUTE, JSON.stringify(seed));
-        }
-    }
-    constructor() {
-        super();
-        // Lit's SSR routes a slotted child's events slot → getRootNode() → host, and the root is
-        // only this element's shadow root if one exists; the renderer never calls connectedCallback
-        // (which would create it), so attach it here.
-        this.attachShadow({ mode: 'open' });
-        this.addEventListener(STORES_REQUEST, (event) => {
-            event.stopPropagation();
-            event.detail.registry = providerScope(this);
-        });
-    }
-    render() {
-        return html `<slot></slot>`;
-    }
-}
-/**
- * Registers `<gyral-stores>` for server renders; `@gyral/ssr` calls it. A no-op in the browser,
- * where a plain `<gyral-stores>` element already scopes stores and the server's shadow root
- * (a `<slot>`) needs no JavaScript. Idempotent.
- */
-export function defineStoresProvider() {
-    if (onServer && customElements.get(STORES_ELEMENT) === undefined) {
-        customElements.define(STORES_ELEMENT, GyralStores);
-    }
-}
+import { STORE_SEED_ATTRIBUTE, STORES_ELEMENT, StoreRegistry } from './store-scope.js';
+import { DEV } from './view/index.js';
+export const storesProvider = {
+    tag: STORES_ELEMENT,
+    open({ properties }) {
+        const listed = properties['instances'];
+        const instances = Array.isArray(listed) ? listed : [];
+        const registry = new StoreRegistry(instances);
+        if (instances.length === 0)
+            return { scope: registry, attributes: {} };
+        const snapshot = registry.snapshot();
+        if (DEV)
+            warnJsonHazard(`<${STORES_ELEMENT}>`, snapshot, 'seed');
+        return { scope: registry, attributes: { [STORE_SEED_ATTRIBUTE]: JSON.stringify(snapshot) } };
+    },
+};
 //# sourceMappingURL=stores-provider.js.map

package/dist/stores-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"stores-provider.js","sourceRoot":"","sources":["../src/stores-provider.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,8FAA8F;AAC9F,+FAA+F;AAC/F,uEAAuE;AACvE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,cAAc,GAEf,MAAM,kBAAkB,CAAC;AAE1B,MAAM,QAAQ,GAAY,QAAQ,CAAC;AAEnC,+FAA+F;AAC/F,MAAM,WAAY,SAAQ,UAAU;aAClB,WAAM,GAAG,GAAG,CAAA;;;;GAI3B,CAAC;IAEF,UAAU,CAA0C;IAEpD,yFAAyF;IACzF,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,IAAI,SAAS,CAAC,KAA8C;QAC1D,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;QACxB,kFAAkF;QAClF,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC3E,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBACjD,cAAc,CAAC,UAAU,IAAI,SAAS,cAAc,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;YAC3E,CAAC;YACD,IAAI,CAAC,YAAY,CAAC,oBAAoB,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;IAED;QACE,KAAK,EAAE,CAAC;QACR,yFAAyF;QACzF,4FAA4F;QAC5F,8CAA8C;QAC9C,IAAI,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACpC,IAAI,CAAC,gBAAgB,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,EAAE;YAC9C,KAAK,CAAC,eAAe,EAAE,CAAC;YACvB,KAAoC,CAAC,MAAM,CAAC,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QAC9E,CAAC,CAAC,CAAC;IACL,CAAC;IAEkB,MAAM;QACvB,OAAO,IAAI,CAAA,eAAe,CAAC;IAC7B,CAAC;;AAGH;;;;GAIG;AACH,MAAM,UAAU,oBAAoB;IAClC,IAAI,QAAQ,IAAI,cAAc,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,SAAS,EAAE,CAAC;QACjE,cAAc,CAAC,MAAM,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IACrD,CAAC;AACH,CAAC","sourcesContent":["// `<gyral-stores>` as a real element for server rendering (gyral-czi.20, ADR 0013 addendum).\n// On the client a provider is a plain element (scopeFor walks the DOM). On the server it must\n// be a registered element: components find it through Lit's SSR event path, and its instances'\n// states are written to `data-gyral-stores` for the client to restore.\nimport { css, html, isServer, LitElement } from 'lit';\nimport { warnJsonHazard } from './json-safety.js';\nimport type { AnyStoreInstance } from './store.js';\nimport {\n  providerScope,\n  STORE_SEED_ATTRIBUTE,\n  STORES_ELEMENT,\n  STORES_REQUEST,\n  type StoresRequest,\n} from './store-scope.js';\n\nconst onServer: boolean = isServer;\n\n/** Server-only element: renders `<slot>` in Declarative Shadow DOM, so children show as-is. */\nclass GyralStores extends LitElement {\n  static override styles = css`\n    :host {\n      display: contents;\n    }\n  `;\n\n  #instances: readonly AnyStoreInstance[] | undefined;\n\n  /** This subtree's store instances; stores not listed start from their seed or `init`. */\n  get instances(): readonly AnyStoreInstance[] | undefined {\n    return this.#instances;\n  }\n\n  set instances(value: readonly AnyStoreInstance[] | undefined) {\n    this.#instances = value;\n    // Written before the attributes render; the client restores it (providerScope()).\n    if (value !== undefined && value.length > 0) {\n      const seed = Object.fromEntries(value.map((i) => [i.store.name, i.state]));\n      for (const [name, state] of Object.entries(seed)) {\n        warnJsonHazard(`store \"${name}\" in <${STORES_ELEMENT}>`, state, 'state');\n      }\n      this.setAttribute(STORE_SEED_ATTRIBUTE, JSON.stringify(seed));\n    }\n  }\n\n  constructor() {\n    super();\n    // Lit's SSR routes a slotted child's events slot → getRootNode() → host, and the root is\n    // only this element's shadow root if one exists; the renderer never calls connectedCallback\n    // (which would create it), so attach it here.\n    this.attachShadow({ mode: 'open' });\n    this.addEventListener(STORES_REQUEST, (event) => {\n      event.stopPropagation();\n      (event as CustomEvent<StoresRequest>).detail.registry = providerScope(this);\n    });\n  }\n\n  protected override render(): unknown {\n    return html`<slot></slot>`;\n  }\n}\n\n/**\n * Registers `<gyral-stores>` for server renders; `@gyral/ssr` calls it. A no-op in the browser,\n * where a plain `<gyral-stores>` element already scopes stores and the server's shadow root\n * (a `<slot>`) needs no JavaScript. Idempotent.\n */\nexport function defineStoresProvider(): void {\n  if (onServer && customElements.get(STORES_ELEMENT) === undefined) {\n    customElements.define(STORES_ELEMENT, GyralStores);\n  }\n}\n"]}
+{"version":3,"file":"stores-provider.js","sourceRoot":"","sources":["../src/stores-provider.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,gGAAgG;AAChG,6FAA6F;AAC7F,wFAAwF;AACxF,uFAAuF;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEvF,OAAO,EAAE,GAAG,EAAuB,MAAM,iBAAiB,CAAC;AAE3D,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC5C,GAAG,EAAE,cAAc;IACnB,IAAI,CAAC,EAAE,UAAU,EAAE;QACjB,MAAM,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;QACvC,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAE,MAAsC,CAAC,CAAC,CAAC,EAAE,CAAC;QACvF,MAAM,QAAQ,GAAG,IAAI,aAAa,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;QACvE,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACrC,IAAI,GAAG;YAAE,cAAc,CAAC,IAAI,cAAc,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QACjE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,CAAC,oBAAoB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;IAC/F,CAAC;CACF,CAAC","sourcesContent":["// `<gyral-stores>` on the server (ADR 0013, view/06-server.md \"Components\"). In the browser a\n// provider is a plain element: scopeFor() walks the DOM to it. On the server it is written as a\n// plain element too, and the renderer gives its subtree the provider's registry (components'\n// `ctx.read` resolves there) and writes its `data-gyral-stores` seed: the states of the\n// instances passed in `.instances`. Stores not listed start from `init` on both sides.\nimport { warnJsonHazard } from './json-safety.js';\nimport { STORE_SEED_ATTRIBUTE, STORES_ELEMENT, StoreRegistry } from './store-scope.js';\nimport type { AnyStoreInstance } from './store.js';\nimport { DEV, type ServerProvider } from './view/index.js';\n\nexport const storesProvider: ServerProvider = {\n  tag: STORES_ELEMENT,\n  open({ properties }) {\n    const listed = properties['instances'];\n    const instances = Array.isArray(listed) ? (listed as readonly AnyStoreInstance[]) : [];\n    const registry = new StoreRegistry(instances);\n    if (instances.length === 0) return { scope: registry, attributes: {} };\n    const snapshot = registry.snapshot();\n    if (DEV) warnJsonHazard(`<${STORES_ELEMENT}>`, snapshot, 'seed');\n    return { scope: registry, attributes: { [STORE_SEED_ATTRIBUTE]: JSON.stringify(snapshot) } };\n  },\n};\n"]}

package/dist/transitions.d.ts

@@ -1,9 +1,8 @@
 /** True when a view transition may run now (API present, motion not reduced). */
-export declare function canTransition(): boolean;
+export declare const canTransition: () => boolean;
 /**
- * Runs `update` inside `document.startViewTransition` when allowed, otherwise directly.
- * `update` must resolve once the DOM reflects the new state. The returned promise settles when
- * `update` has run. A transition skipped by a newer one still runs its update (per spec); its
- * rejected `ready` is expected and swallowed.
+ * Runs `update` (a whole flush) as a view transition's update callback. A transition skipped
+ * by a newer one still runs its update (per spec); its rejected promises are expected and
+ * swallowed. Call only after `canTransition()`.
  */
-export declare function withViewTransition(update: () => Promise<void>): Promise<void>;
+export declare function startTransition(update: () => void): void;

package/dist/transitions.js

@@ -1,26 +1,17 @@
-// View Transitions for define() components (ADR 0001 addendum). An ADR 0003 enhancement:
-// without the API, or with reduced motion requested, updates render normally.
-const supportsViewTransitions = (doc) => 'startViewTransition' in doc;
+// View Transitions for the scheduler (view/04-scheduler.md "View transitions", ADR 0001
+// addendum). An ADR 0003 enhancement: without the API, or with reduced motion requested, the
+// flush runs as normal.
 const ignore = () => undefined;
 /** True when a view transition may run now (API present, motion not reduced). */
-export function canTransition() {
-    if (typeof document === 'undefined' || !supportsViewTransitions(document))
-        return false;
-    return !window.matchMedia('(prefers-reduced-motion: reduce)').matches;
-}
+export const canTransition = () => 'startViewTransition' in document && !matchMedia('(prefers-reduced-motion: reduce)').matches;
 /**
- * Runs `update` inside `document.startViewTransition` when allowed, otherwise directly.
- * `update` must resolve once the DOM reflects the new state. The returned promise settles when
- * `update` has run. A transition skipped by a newer one still runs its update (per spec); its
- * rejected `ready` is expected and swallowed.
+ * Runs `update` (a whole flush) as a view transition's update callback. A transition skipped
+ * by a newer one still runs its update (per spec); its rejected promises are expected and
+ * swallowed. Call only after `canTransition()`.
  */
-export function withViewTransition(update) {
-    if (!canTransition() || !supportsViewTransitions(document))
-        return update();
-    return new Promise((resolve, reject) => {
-        const transition = document.startViewTransition(() => update().then(resolve, reject));
-        transition.ready.catch(ignore);
-        transition.finished.catch(ignore);
-    });
+export function startTransition(update) {
+    const transition = document.startViewTransition(update);
+    transition.ready.catch(ignore);
+    transition.finished.catch(ignore);
 }
 //# sourceMappingURL=transitions.js.map

package/dist/transitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../src/transitions.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,8EAA8E;AAW9E,MAAM,uBAAuB,GAAG,CAAC,GAAa,EAA4C,EAAE,CAC1F,qBAAqB,IAAI,GAAG,CAAC;AAE/B,MAAM,MAAM,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC;AAErC,iFAAiF;AACjF,MAAM,UAAU,aAAa;IAC3B,IAAI,OAAO,QAAQ,KAAK,WAAW,IAAI,CAAC,uBAAuB,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IACxF,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,kCAAkC,CAAC,CAAC,OAAO,CAAC;AACxE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA2B;IAC5D,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,uBAAuB,CAAC,QAAQ,CAAC;QAAE,OAAO,MAAM,EAAE,CAAC;IAC5E,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,UAAU,GAAG,QAAQ,CAAC,mBAAmB,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;QACtF,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/B,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["// View Transitions for define() components (ADR 0001 addendum). An ADR 0003 enhancement:\n// without the API, or with reduced motion requested, updates render normally.\n\ninterface ViewTransitionLike {\n  readonly ready: Promise<unknown>;\n  readonly finished: Promise<unknown>;\n}\n\ninterface ViewTransitionDocument {\n  startViewTransition(update: () => Promise<void>): ViewTransitionLike;\n}\n\nconst supportsViewTransitions = (doc: Document): doc is Document & ViewTransitionDocument =>\n  'startViewTransition' in doc;\n\nconst ignore = (): void => undefined;\n\n/** True when a view transition may run now (API present, motion not reduced). */\nexport function canTransition(): boolean {\n  if (typeof document === 'undefined' || !supportsViewTransitions(document)) return false;\n  return !window.matchMedia('(prefers-reduced-motion: reduce)').matches;\n}\n\n/**\n * Runs `update` inside `document.startViewTransition` when allowed, otherwise directly.\n * `update` must resolve once the DOM reflects the new state. The returned promise settles when\n * `update` has run. A transition skipped by a newer one still runs its update (per spec); its\n * rejected `ready` is expected and swallowed.\n */\nexport function withViewTransition(update: () => Promise<void>): Promise<void> {\n  if (!canTransition() || !supportsViewTransitions(document)) return update();\n  return new Promise((resolve, reject) => {\n    const transition = document.startViewTransition(() => update().then(resolve, reject));\n    transition.ready.catch(ignore);\n    transition.finished.catch(ignore);\n  });\n}\n"]}
+{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../src/transitions.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,6FAA6F;AAC7F,wBAAwB;AAWxB,MAAM,MAAM,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC;AAErC,iFAAiF;AACjF,MAAM,CAAC,MAAM,aAAa,GAAG,GAAY,EAAE,CACzC,qBAAqB,IAAI,QAAQ,IAAI,CAAC,UAAU,CAAC,kCAAkC,CAAC,CAAC,OAAO,CAAC;AAE/F;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAkB;IAChD,MAAM,UAAU,GAAI,QAA8C,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC/F,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC","sourcesContent":["// View Transitions for the scheduler (view/04-scheduler.md \"View transitions\", ADR 0001\n// addendum). An ADR 0003 enhancement: without the API, or with reduced motion requested, the\n// flush runs as normal.\n\ninterface ViewTransitionLike {\n  readonly ready: Promise<unknown>;\n  readonly finished: Promise<unknown>;\n}\n\ninterface ViewTransitionDocument {\n  startViewTransition(update: () => void): ViewTransitionLike;\n}\n\nconst ignore = (): void => undefined;\n\n/** True when a view transition may run now (API present, motion not reduced). */\nexport const canTransition = (): boolean =>\n  'startViewTransition' in document && !matchMedia('(prefers-reduced-motion: reduce)').matches;\n\n/**\n * Runs `update` (a whole flush) as a view transition's update callback. A transition skipped\n * by a newer one still runs its update (per spec); its rejected promises are expected and\n * swallowed. Call only after `canTransition()`.\n */\nexport function startTransition(update: () => void): void {\n  const transition = (document as Document & ViewTransitionDocument).startViewTransition(update);\n  transition.ready.catch(ignore);\n  transition.finished.catch(ignore);\n}\n"]}

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-import type { PropertyDeclaration } from 'lit';
-import type { Styles } from './styles.js';
+import type { Prop } from './prop.js';
+import type { ChildValue, Styles } from './view/index.js';
 import type { CommandInfo } from './invokers.js';
 import type { HydrateStrategy } from './islands.js';
 import type { DriverOverrides, Next } from './command.js';
@@ -106,25 +106,13 @@ export type IntentNames<M extends Tagged> = {
     readonly [K in M['_tag']]: K;
 };
 /**
- * One prop's declaration: Lit's `PropertyDeclaration` plus Gyral's honesty rule (ADR 0007
- * addendum). A prop is `undefined` until a parent, an attribute or a hydration seed sets it,
- * so a prop whose type excludes `undefined` must say how that is guaranteed:
- * - `required: true`: a missing value is a bug, reported once per instance at first render;
- * - `default: value`: used whenever the element's value is `undefined`.
- * A prop whose type includes `undefined` needs neither.
+ * The prop builders for props type `P` (view/05-element.md "Props"): one `prop.*` builder per
+ * key. A builder's output type must fit the prop's type, so a prop whose type excludes
+ * `undefined` needs `required: true` or a `default` (the honesty rule, ADR 0007 addendum).
+ * Without explicit type arguments, `define()` infers `P` from the builders.
  */
-export type PropDeclaration<T> = PropertyDeclaration & (undefined extends T ? {
-    readonly required?: false;
-    readonly default?: T;
-} : {
-    readonly required: true;
-    readonly default?: undefined;
-} | {
-    readonly required?: false;
-    readonly default: T;
-});
 export type PropDeclarations<P> = {
-    readonly [K in keyof P]-?: PropDeclaration<P[K]>;
+    readonly [K in keyof P]-?: Prop<P[K]>;
 };
 /** State of a component that keeps none (a pure view of its props). Its `init` is optional. */
 export type Stateless = Readonly<Record<string, never>>;
@@ -137,17 +125,17 @@ type InitField<S, M extends Tagged, P> = Stateless extends S ? {
 };
 export type ComponentSpec<S, M extends Tagged, P> = SpecBody<S, M, P> & InitField<S, M, P>;
 interface SpecBody<S, M extends Tagged, P> {
-    /** Lit reactive property declarations: the component's inputs. */
+    /** The component's inputs, declared with `prop.*` builders. */
     readonly props?: PropDeclarations<P>;
     /** INTENT: platform events to messages. */
     readonly intent: Intents<M>;
     /** MODEL: pure state transitions. */
     readonly update: Update<S, M, P>;
     /** VIEW: pure function of state and props. Name intents in markup; never attach closures. */
-    readonly view: (state: S, intents: IntentNames<M>, ctx: Ctx<P>) => unknown;
+    readonly view: (state: S, intents: IntentNames<M>, ctx: Ctx<P>) => ChildValue;
     /**
-     * Shadow-root styles: `css` templates, plain CSS strings, `CSSStyleSheet`s, or arrays of
-     * them. Ignored (with a warning) when `shadow: false`.
+     * Shadow-root styles: `css` values, plain CSS strings, or arrays of them, nested freely.
+     * Each maps to one shared `CSSStyleSheet`. Ignored (with a warning) when `shadow: false`.
      */
     readonly styles?: Styles;
     /**
@@ -176,6 +164,14 @@ interface SpecBody<S, M extends Tagged, P> {
      * reorders). Skipped without browser support or when reduced motion is requested.
      */
     readonly viewTransition?: (prev: S, next: S, msg: Tagged) => boolean;
+    /**
+     * Messages from bursty sources (a WebSocket feed, a sensor) whose renders wait for the next
+     * animation frame, so many messages in one frame cost one render: `renderOnFrame: ['Ticked']`.
+     * Reducers still run at once. Any other change to the component renders in the usual
+     * microtask flush, taking pending frame work with it. `'StoreChanged'` covers store changes.
+     * Pages that get no frames (hidden) render from a 100 ms timer. view/04-scheduler.md.
+     */
+    readonly renderOnFrame?: readonly (M['_tag'] | 'StoreChanged')[];
     /**
      * Boolean facts about the state, exposed to CSS as custom states:
      * `states: (s) => ({ loading: s._tag === 'Loading' })` enables `:host(:state(loading))` and

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { PropertyDeclaration } from 'lit';\nimport type { Styles } from './styles.js';\nimport type { CommandInfo } from './invokers.js';\nimport type { HydrateStrategy } from './islands.js';\nimport type { DriverOverrides, Next } from './command.js';\nimport type { AnyStore, StoreChanged, StoreRef } from './store.js';\n\n/** Every message is a tagged object; the tag is also the intent name used in markup. */\nexport interface Tagged {\n  readonly _tag: string;\n}\n\n/** What the intent layer sees when a `data-intent` element fires its trigger event. */\nexport interface IntentInput {\n  /** The `data-intent` value (a message tag). */\n  readonly name: string;\n  readonly event: Event;\n  /** The element carrying `data-intent`. */\n  readonly target: Element;\n  /** `value` of the input, select, textarea or button that carries the intent. */\n  readonly value: string | undefined;\n  /** `checked` for checkbox and radio inputs. */\n  readonly checked: boolean | undefined;\n  /** Submitted data (including the submitter button) when the intent is on a `<form>`. */\n  readonly formData: FormData | undefined;\n  /** The output a child component emitted, when the intent is on a child element. */\n  readonly detail: unknown;\n  /** `KeyboardEvent.key` for `keydown`/`keyup` intents. */\n  readonly key: string | undefined;\n  /** For `toggle` intents (popover, `<details>`): the state it changed to. */\n  readonly newState: 'open' | 'closed' | undefined;\n  /** For `command` intents: the invoker's command (e.g. `--clear`) and source (gyral-czi.6). */\n  readonly command: CommandInfo | undefined;\n}\n\n/** Reads a declared store's current state, typed by the store (ADR 0013). */\nexport type StoreReader = <S>(store: StoreRef<S>) => S;\n\n/** Read-only context handed to every reducer and to the view (ADR 0007, 0013). */\nexport interface Ctx<P> {\n  /** Props from above. */\n  readonly props: P;\n  /** Stores from the side: `read(cart).lines`. The store must be in `spec.stores`. */\n  readonly read: StoreReader;\n}\n\n/** Framework message: declared props changed after the first render (ADR 0007). */\nexport interface PropsChanged<P> {\n  readonly _tag: 'PropsChanged';\n  readonly props: P;\n  readonly prev: P;\n}\n\n/**\n * Framework message: the component is live in the browser (ADR 0012 addendum). Sent once,\n * after the first client render has completed, to every client-side instance. Use it for\n * progressive enhancement: render the no-JS form on the server and in the first client render\n * (so hydration matches), then switch to the enhanced UI in the `Hydrated` reducer.\n */\nexport interface Hydrated {\n  readonly _tag: 'Hydrated';\n  /** `true` when the instance resumed from server-rendered markup (a hydration seed). */\n  readonly serverRendered: boolean;\n}\n\n/** One validation problem. `path` is dot-joined and matches the field's `name`. */\nexport interface FieldIssue {\n  readonly path: string;\n  readonly message: string;\n}\n\n/** Submitted text values of a form (Files are dropped: they can't be re-filled). */\nexport type FormFields = Readonly<Record<string, string | readonly string[]>>;\n\n/** Framework message: an intent's input failed schema validation (ADR 0008). */\nexport interface IntentRejected {\n  readonly _tag: 'IntentRejected';\n  /** The `data-intent` name whose input was rejected. */\n  readonly intent: string;\n  readonly issues: readonly FieldIssue[];\n  /**\n   * For `form()` rejections: what the user submitted, so the view can re-fill the form. On\n   * the no-JS path (ADR 0008 server half) the server re-renders the page from this.\n   */\n  // `| undefined` so schemas with plain optional fields (valibot `optional`) can produce it.\n  readonly values?: FormFields | undefined;\n}\n\ntype ParseResult<M> = M | IntentRejected | undefined;\n\n/**\n * Parses a platform event into one message variant, `IntentRejected`, or `undefined` to\n * ignore it. May be async because schema validation may be.\n */\nexport type IntentParser<M> = (input: IntentInput) => ParseResult<M> | Promise<ParseResult<M>>;\n\ntype Variant<M extends Tagged, K extends M['_tag']> = Extract<M, { readonly _tag: K }>;\n\n/** Intent parsers keyed by the message tag they produce. Messages from drivers need none. */\nexport type Intents<M extends Tagged> = {\n  readonly [K in M['_tag']]?: IntentParser<Variant<M, K>>;\n};\n\ntype Reducer<S, M, Msg, P> = (state: S, msg: Msg, ctx: Ctx<P>) => Next<S, M>;\n\n/**\n * One pure reducer per message tag (exhaustive by construction), plus optional reducers\n * for framework messages. Reducers may return commands.\n */\nexport type Update<S, M extends Tagged, P = object> = {\n  readonly [K in M['_tag']]: Reducer<S, M, Variant<M, K>, P>;\n} & {\n  readonly PropsChanged?: Reducer<S, M, PropsChanged<P>, P>;\n  readonly IntentRejected?: Reducer<S, M, IntentRejected, P>;\n  readonly StoreChanged?: Reducer<S, M, StoreChanged, P>;\n  readonly Hydrated?: Reducer<S, M, Hydrated, P>;\n};\n\n/** Typed intent names handed to the view, so `data-intent=${i.Increment}` is checked. */\nexport type IntentNames<M extends Tagged> = { readonly [K in M['_tag']]: K };\n\n/**\n * One prop's declaration: Lit's `PropertyDeclaration` plus Gyral's honesty rule (ADR 0007\n * addendum). A prop is `undefined` until a parent, an attribute or a hydration seed sets it,\n * so a prop whose type excludes `undefined` must say how that is guaranteed:\n * - `required: true`: a missing value is a bug, reported once per instance at first render;\n * - `default: value`: used whenever the element's value is `undefined`.\n * A prop whose type includes `undefined` needs neither.\n */\nexport type PropDeclaration<T> = PropertyDeclaration &\n  (undefined extends T\n    ? { readonly required?: false; readonly default?: T }\n    : | { readonly required: true; readonly default?: undefined }\n      | { readonly required?: false; readonly default: T });\n\nexport type PropDeclarations<P> = { readonly [K in keyof P]-?: PropDeclaration<P[K]> };\n\n/** State of a component that keeps none (a pure view of its props). Its `init` is optional. */\nexport type Stateless = Readonly<Record<string, never>>;\n\n/** Initial model state (and optional commands), computed from props on first render. */\ntype Init<S, M, P> = (props: P) => Next<S, M>;\n\n// `init` may be omitted only when an empty object is a valid state (Stateless, all-optional).\ntype InitField<S, M extends Tagged, P> = Stateless extends S\n  ? { readonly init?: Init<S, M, P> }\n  : { readonly init: Init<S, M, P> };\n\nexport type ComponentSpec<S, M extends Tagged, P> = SpecBody<S, M, P> & InitField<S, M, P>;\n\ninterface SpecBody<S, M extends Tagged, P> {\n  /** Lit reactive property declarations: the component's inputs. */\n  readonly props?: PropDeclarations<P>;\n  /** INTENT: platform events to messages. */\n  readonly intent: Intents<M>;\n  /** MODEL: pure state transitions. */\n  readonly update: Update<S, M, P>;\n  /** VIEW: pure function of state and props. Name intents in markup; never attach closures. */\n  readonly view: (state: S, intents: IntentNames<M>, ctx: Ctx<P>) => unknown;\n  /**\n   * Shadow-root styles: `css` templates, plain CSS strings, `CSSStyleSheet`s, or arrays of\n   * them. Ignored (with a warning) when `shadow: false`.\n   */\n  readonly styles?: Styles;\n  /**\n   * `false` renders the view as the element's own light-DOM children (ADR 0014): document CSS\n   * applies, and the server writes plain children instead of a `<template shadowrootmode>`.\n   * For page-level components (listings, articles). No `<slot>`s and no `styles`. Default `true`.\n   */\n  readonly shadow?: boolean;\n  /**\n   * When a server-rendered instance hydrates (gyral-4k7.4): `load` (default), `idle`,\n   * `visible` (scrolled into view) or `interaction` (first pointer/focus). Client-only\n   * renders are unaffected.\n   */\n  readonly hydrate?: HydrateStrategy;\n  /** Extra event types that may trigger intents via `data-intent-on` (e.g. `pointerdown`). */\n  readonly events?: readonly string[];\n  /** Driver substitutions by name, for every instance (ADR 0006). */\n  readonly drivers?: DriverOverrides;\n  /**\n   * Stores this component reads with `ctx.read(store)` and writes with `send(store, msg)`.\n   * Their changes re-render it (and reach the optional `StoreChanged` reducer). ADR 0013.\n   */\n  readonly stores?: readonly AnyStore[];\n  /**\n   * Return `true` to render this state change inside a View Transition (route changes, list\n   * reorders). Skipped without browser support or when reduced motion is requested.\n   */\n  readonly viewTransition?: (prev: S, next: S, msg: Tagged) => boolean;\n  /**\n   * Boolean facts about the state, exposed to CSS as custom states:\n   * `states: (s) => ({ loading: s._tag === 'Loading' })` enables `:host(:state(loading))` and\n   * `gy-x:state(loading)`. Applied after each render; feature-detected; not on the server.\n   */\n  readonly states?: (state: S) => Readonly<Record<string, boolean>>;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Prop } from './prop.js';\nimport type { ChildValue, Styles } from './view/index.js';\nimport type { CommandInfo } from './invokers.js';\nimport type { HydrateStrategy } from './islands.js';\nimport type { DriverOverrides, Next } from './command.js';\nimport type { AnyStore, StoreChanged, StoreRef } from './store.js';\n\n/** Every message is a tagged object; the tag is also the intent name used in markup. */\nexport interface Tagged {\n  readonly _tag: string;\n}\n\n/** What the intent layer sees when a `data-intent` element fires its trigger event. */\nexport interface IntentInput {\n  /** The `data-intent` value (a message tag). */\n  readonly name: string;\n  readonly event: Event;\n  /** The element carrying `data-intent`. */\n  readonly target: Element;\n  /** `value` of the input, select, textarea or button that carries the intent. */\n  readonly value: string | undefined;\n  /** `checked` for checkbox and radio inputs. */\n  readonly checked: boolean | undefined;\n  /** Submitted data (including the submitter button) when the intent is on a `<form>`. */\n  readonly formData: FormData | undefined;\n  /** The output a child component emitted, when the intent is on a child element. */\n  readonly detail: unknown;\n  /** `KeyboardEvent.key` for `keydown`/`keyup` intents. */\n  readonly key: string | undefined;\n  /** For `toggle` intents (popover, `<details>`): the state it changed to. */\n  readonly newState: 'open' | 'closed' | undefined;\n  /** For `command` intents: the invoker's command (e.g. `--clear`) and source (gyral-czi.6). */\n  readonly command: CommandInfo | undefined;\n}\n\n/** Reads a declared store's current state, typed by the store (ADR 0013). */\nexport type StoreReader = <S>(store: StoreRef<S>) => S;\n\n/** Read-only context handed to every reducer and to the view (ADR 0007, 0013). */\nexport interface Ctx<P> {\n  /** Props from above. */\n  readonly props: P;\n  /** Stores from the side: `read(cart).lines`. The store must be in `spec.stores`. */\n  readonly read: StoreReader;\n}\n\n/** Framework message: declared props changed after the first render (ADR 0007). */\nexport interface PropsChanged<P> {\n  readonly _tag: 'PropsChanged';\n  readonly props: P;\n  readonly prev: P;\n}\n\n/**\n * Framework message: the component is live in the browser (ADR 0012 addendum). Sent once,\n * after the first client render has completed, to every client-side instance. Use it for\n * progressive enhancement: render the no-JS form on the server and in the first client render\n * (so hydration matches), then switch to the enhanced UI in the `Hydrated` reducer.\n */\nexport interface Hydrated {\n  readonly _tag: 'Hydrated';\n  /** `true` when the instance resumed from server-rendered markup (a hydration seed). */\n  readonly serverRendered: boolean;\n}\n\n/** One validation problem. `path` is dot-joined and matches the field's `name`. */\nexport interface FieldIssue {\n  readonly path: string;\n  readonly message: string;\n}\n\n/** Submitted text values of a form (Files are dropped: they can't be re-filled). */\nexport type FormFields = Readonly<Record<string, string | readonly string[]>>;\n\n/** Framework message: an intent's input failed schema validation (ADR 0008). */\nexport interface IntentRejected {\n  readonly _tag: 'IntentRejected';\n  /** The `data-intent` name whose input was rejected. */\n  readonly intent: string;\n  readonly issues: readonly FieldIssue[];\n  /**\n   * For `form()` rejections: what the user submitted, so the view can re-fill the form. On\n   * the no-JS path (ADR 0008 server half) the server re-renders the page from this.\n   */\n  // `| undefined` so schemas with plain optional fields (valibot `optional`) can produce it.\n  readonly values?: FormFields | undefined;\n}\n\ntype ParseResult<M> = M | IntentRejected | undefined;\n\n/**\n * Parses a platform event into one message variant, `IntentRejected`, or `undefined` to\n * ignore it. May be async because schema validation may be.\n */\nexport type IntentParser<M> = (input: IntentInput) => ParseResult<M> | Promise<ParseResult<M>>;\n\ntype Variant<M extends Tagged, K extends M['_tag']> = Extract<M, { readonly _tag: K }>;\n\n/** Intent parsers keyed by the message tag they produce. Messages from drivers need none. */\nexport type Intents<M extends Tagged> = {\n  readonly [K in M['_tag']]?: IntentParser<Variant<M, K>>;\n};\n\ntype Reducer<S, M, Msg, P> = (state: S, msg: Msg, ctx: Ctx<P>) => Next<S, M>;\n\n/**\n * One pure reducer per message tag (exhaustive by construction), plus optional reducers\n * for framework messages. Reducers may return commands.\n */\nexport type Update<S, M extends Tagged, P = object> = {\n  readonly [K in M['_tag']]: Reducer<S, M, Variant<M, K>, P>;\n} & {\n  readonly PropsChanged?: Reducer<S, M, PropsChanged<P>, P>;\n  readonly IntentRejected?: Reducer<S, M, IntentRejected, P>;\n  readonly StoreChanged?: Reducer<S, M, StoreChanged, P>;\n  readonly Hydrated?: Reducer<S, M, Hydrated, P>;\n};\n\n/** Typed intent names handed to the view, so `data-intent=${i.Increment}` is checked. */\nexport type IntentNames<M extends Tagged> = { readonly [K in M['_tag']]: K };\n\n/**\n * The prop builders for props type `P` (view/05-element.md \"Props\"): one `prop.*` builder per\n * key. A builder's output type must fit the prop's type, so a prop whose type excludes\n * `undefined` needs `required: true` or a `default` (the honesty rule, ADR 0007 addendum).\n * Without explicit type arguments, `define()` infers `P` from the builders.\n */\nexport type PropDeclarations<P> = { readonly [K in keyof P]-?: Prop<P[K]> };\n\n/** State of a component that keeps none (a pure view of its props). Its `init` is optional. */\nexport type Stateless = Readonly<Record<string, never>>;\n\n/** Initial model state (and optional commands), computed from props on first render. */\ntype Init<S, M, P> = (props: P) => Next<S, M>;\n\n// `init` may be omitted only when an empty object is a valid state (Stateless, all-optional).\ntype InitField<S, M extends Tagged, P> = Stateless extends S\n  ? { readonly init?: Init<S, M, P> }\n  : { readonly init: Init<S, M, P> };\n\nexport type ComponentSpec<S, M extends Tagged, P> = SpecBody<S, M, P> & InitField<S, M, P>;\n\ninterface SpecBody<S, M extends Tagged, P> {\n  /** The component's inputs, declared with `prop.*` builders. */\n  readonly props?: PropDeclarations<P>;\n  /** INTENT: platform events to messages. */\n  readonly intent: Intents<M>;\n  /** MODEL: pure state transitions. */\n  readonly update: Update<S, M, P>;\n  /** VIEW: pure function of state and props. Name intents in markup; never attach closures. */\n  readonly view: (state: S, intents: IntentNames<M>, ctx: Ctx<P>) => ChildValue;\n  /**\n   * Shadow-root styles: `css` values, plain CSS strings, or arrays of them, nested freely.\n   * Each maps to one shared `CSSStyleSheet`. Ignored (with a warning) when `shadow: false`.\n   */\n  readonly styles?: Styles;\n  /**\n   * `false` renders the view as the element's own light-DOM children (ADR 0014): document CSS\n   * applies, and the server writes plain children instead of a `<template shadowrootmode>`.\n   * For page-level components (listings, articles). No `<slot>`s and no `styles`. Default `true`.\n   */\n  readonly shadow?: boolean;\n  /**\n   * When a server-rendered instance hydrates (gyral-4k7.4): `load` (default), `idle`,\n   * `visible` (scrolled into view) or `interaction` (first pointer/focus). Client-only\n   * renders are unaffected.\n   */\n  readonly hydrate?: HydrateStrategy;\n  /** Extra event types that may trigger intents via `data-intent-on` (e.g. `pointerdown`). */\n  readonly events?: readonly string[];\n  /** Driver substitutions by name, for every instance (ADR 0006). */\n  readonly drivers?: DriverOverrides;\n  /**\n   * Stores this component reads with `ctx.read(store)` and writes with `send(store, msg)`.\n   * Their changes re-render it (and reach the optional `StoreChanged` reducer). ADR 0013.\n   */\n  readonly stores?: readonly AnyStore[];\n  /**\n   * Return `true` to render this state change inside a View Transition (route changes, list\n   * reorders). Skipped without browser support or when reduced motion is requested.\n   */\n  readonly viewTransition?: (prev: S, next: S, msg: Tagged) => boolean;\n  /**\n   * Messages from bursty sources (a WebSocket feed, a sensor) whose renders wait for the next\n   * animation frame, so many messages in one frame cost one render: `renderOnFrame: ['Ticked']`.\n   * Reducers still run at once. Any other change to the component renders in the usual\n   * microtask flush, taking pending frame work with it. `'StoreChanged'` covers store changes.\n   * Pages that get no frames (hidden) render from a 100 ms timer. view/04-scheduler.md.\n   */\n  readonly renderOnFrame?: readonly (M['_tag'] | 'StoreChanged')[];\n  /**\n   * Boolean facts about the state, exposed to CSS as custom states:\n   * `states: (s) => ({ loading: s._tag === 'Loading' })` enables `:host(:state(loading))` and\n   * `gy-x:state(loading)`. Applied after each render; feature-detected; not on the server.\n   */\n  readonly states?: (state: S) => Readonly<Record<string, boolean>>;\n}\n"]}

package/dist/view/attributes.d.ts

@@ -0,0 +1,6 @@
+/** Host attribute holding a component's JSON seed (ADR 0012); the client removes it. */
+export declare const SEED_ATTRIBUTE = "data-gyral-seed";
+/** Marks a server-rendered light-DOM host (ADR 0014), so hydration knows its own content. */
+export declare const LIGHT_ATTRIBUTE = "data-gyral-light";
+/** A deferred island's strategy (07 "Islands"), next to `defer-hydration`. */
+export declare const ISLAND_ATTRIBUTE = "data-gyral-hydrate";

package/dist/view/attributes.js

@@ -0,0 +1,10 @@
+// Host attributes the server renderer writes (view/06-server.md "Components") and the client
+// reads (07). Core's hydration.ts, light-dom.ts and islands.ts declare the same names for the
+// client; server-components.node.test.ts checks that they match.
+/** Host attribute holding a component's JSON seed (ADR 0012); the client removes it. */
+export const SEED_ATTRIBUTE = 'data-gyral-seed';
+/** Marks a server-rendered light-DOM host (ADR 0014), so hydration knows its own content. */
+export const LIGHT_ATTRIBUTE = 'data-gyral-light';
+/** A deferred island's strategy (07 "Islands"), next to `defer-hydration`. */
+export const ISLAND_ATTRIBUTE = 'data-gyral-hydrate';
+//# sourceMappingURL=attributes.js.map

package/dist/view/attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attributes.js","sourceRoot":"","sources":["../../src/view/attributes.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,8FAA8F;AAC9F,iEAAiE;AACjE,wFAAwF;AACxF,MAAM,CAAC,MAAM,cAAc,GAAG,iBAAiB,CAAC;AAChD,6FAA6F;AAC7F,MAAM,CAAC,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAClD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAG,oBAAoB,CAAC","sourcesContent":["// Host attributes the server renderer writes (view/06-server.md \"Components\") and the client\n// reads (07). Core's hydration.ts, light-dom.ts and islands.ts declare the same names for the\n// client; server-components.node.test.ts checks that they match.\n/** Host attribute holding a component's JSON seed (ADR 0012); the client removes it. */\nexport const SEED_ATTRIBUTE = 'data-gyral-seed';\n/** Marks a server-rendered light-DOM host (ADR 0014), so hydration knows its own content. */\nexport const LIGHT_ATTRIBUTE = 'data-gyral-light';\n/** A deferred island's strategy (07 \"Islands\"), next to `defer-hydration`. */\nexport const ISLAND_ATTRIBUTE = 'data-gyral-hydrate';\n"]}

package/dist/view/compiled.d.ts

@@ -0,0 +1 @@
+export { compiled } from './template.js';

package/dist/view/compiled.js

@@ -0,0 +1,6 @@
+// `@gyral/core/compiled`: the entry the Vite template compiler's output imports `compiled`
+// from (view/01-templates.md "Compiled"). Internal: apps never import it themselves, and it is
+// not documented as API. A subpath of its own, so the main entry's API stays as documented
+// and compiled code still shares the one template module with `html` (same package copy).
+export { compiled } from './template.js';
+//# sourceMappingURL=compiled.js.map

package/dist/view/compiled.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiled.js","sourceRoot":"","sources":["../../src/view/compiled.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,+FAA+F;AAC/F,2FAA2F;AAC3F,0FAA0F;AAC1F,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC","sourcesContent":["// `@gyral/core/compiled`: the entry the Vite template compiler's output imports `compiled`\n// from (view/01-templates.md \"Compiled\"). Internal: apps never import it themselves, and it is\n// not documented as API. A subpath of its own, so the main entry's API stays as documented\n// and compiled code still shares the one template module with `html` (same package copy).\nexport { compiled } from './template.js';\n"]}

package/dist/view/dev-off.d.ts

@@ -0,0 +1 @@
+export declare const DEV: boolean;

package/dist/view/dev-off.js

@@ -0,0 +1,4 @@
+// Production build of the view layer's flag (`#view-dev` without the `development` condition):
+// a literal `false`, so bundlers drop every `if (DEV)` check and warning. See dev.ts.
+export const DEV = false;
+//# sourceMappingURL=dev-off.js.map

package/dist/view/dev-off.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-off.js","sourceRoot":"","sources":["../../src/view/dev-off.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,sFAAsF;AACtF,MAAM,CAAC,MAAM,GAAG,GAAY,KAAK,CAAC","sourcesContent":["// Production build of the view layer's flag (`#view-dev` without the `development` condition):\n// a literal `false`, so bundlers drop every `if (DEV)` check and warning. See dev.ts.\nexport const DEV: boolean = false;\n"]}

package/dist/view/dev.d.ts

@@ -0,0 +1 @@
+export declare const DEV: boolean;

package/dist/view/dev.js

@@ -0,0 +1,5 @@
+// Development build of the view layer's flag, resolved through core's `#view-dev` import with
+// the `development` condition (view/09-template-rules.md "One rule set, three places"). Checks
+// and warnings are guarded with `if (DEV)`; production builds get dev-off.ts, so they vanish.
+export const DEV = true;
+//# sourceMappingURL=dev.js.map

package/dist/view/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.js","sourceRoot":"","sources":["../../src/view/dev.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,+FAA+F;AAC/F,8FAA8F;AAC9F,MAAM,CAAC,MAAM,GAAG,GAAY,IAAI,CAAC","sourcesContent":["// Development build of the view layer's flag, resolved through core's `#view-dev` import with\n// the `development` condition (view/09-template-rules.md \"One rule set, three places\"). Checks\n// and warnings are guarded with `if (DEV)`; production builds get dev-off.ts, so they vanish.\nexport const DEV: boolean = true;\n"]}

package/dist/view/flags.d.ts

@@ -0,0 +1 @@
+export { DEV } from '#view-dev';

package/dist/view/flags.js

@@ -0,0 +1,4 @@
+// The development flag for view/ modules that may not use `#` imports themselves (view/server/,
+// ADR 0018 "Where it lives"): core's `#view-dev`, resolved by the `development` condition.
+export { DEV } from '#view-dev';
+//# sourceMappingURL=flags.js.map

package/dist/view/flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../../src/view/flags.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,2FAA2F;AAC3F,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC","sourcesContent":["// The development flag for view/ modules that may not use `#` imports themselves (view/server/,\n// ADR 0018 \"Where it lives\"): core's `#view-dev`, resolved by the `development` condition.\nexport { DEV } from '#view-dev';\n"]}

package/dist/view/index.d.ts

@@ -0,0 +1,21 @@
+export { DEV } from '#view-dev';
+export { html, compiled, isTemplateResult, templateOf, type TemplateResult } from './template.js';
+export { templateElement } from './template-element.js';
+export { normalize, analyze, type Analysis } from './normalize/normalize.js';
+export { checkTemplate, type TemplateIssue } from './normalize/check.js';
+export { templateId } from './normalize/id.js';
+export { TemplateError } from './normalize/errors.js';
+export { shapeMismatch, repairError } from './normalize/shape.js';
+export type { NormalizedTemplate, PartSpec, Path, Segment, Shape, ShapeNode, TemplateObject, } from './normalize/types.js';
+export { hydrate } from './render/hydrate.js';
+export { render, renderBatch } from './render/render.js';
+export type { Markup, SeenMarkup } from './render/seen.js';
+export { HydrationMismatch } from './render/mismatch.js';
+export { each } from './render/list.js';
+export { raw } from './render/raw.js';
+export { nothing, type ChildValue, type ListResult, type RawResult } from './render/values.js';
+export { defineHook } from './render/hook-part.js';
+export type { HookAttributes, HookResult, HookSpec } from './render/hooks.js';
+export { css, isStyleSource, sheetsFor, styleTexts, type CssValue, type StyleSource, type Styles, } from './styles.js';
+export { ISLAND_ATTRIBUTE, LIGHT_ATTRIBUTE, SEED_ATTRIBUTE } from './attributes.js';
+export { registerServerComponent, registerServerProvider, serverComponent, serverComponents, serverProvider, type ServerComponent, type ServerProvider, type ServerRenderInput, type ServerRendering, } from './registry.js';

package/dist/view/index.js

@@ -0,0 +1,21 @@
+// The view layer's entry point for the rest of core (ADR 0018 "Where it lives"): code outside
+// view/ imports only this module. @gyral/core's index re-exports the public part of it.
+export { DEV } from '#view-dev';
+export { html, compiled, isTemplateResult, templateOf } from './template.js';
+export { templateElement } from './template-element.js';
+export { normalize, analyze } from './normalize/normalize.js';
+export { checkTemplate } from './normalize/check.js';
+export { templateId } from './normalize/id.js';
+export { TemplateError } from './normalize/errors.js';
+export { shapeMismatch, repairError } from './normalize/shape.js';
+export { hydrate } from './render/hydrate.js';
+export { render, renderBatch } from './render/render.js';
+export { HydrationMismatch } from './render/mismatch.js';
+export { each } from './render/list.js';
+export { raw } from './render/raw.js';
+export { nothing } from './render/values.js';
+export { defineHook } from './render/hook-part.js';
+export { css, isStyleSource, sheetsFor, styleTexts, } from './styles.js';
+export { ISLAND_ATTRIBUTE, LIGHT_ATTRIBUTE, SEED_ATTRIBUTE } from './attributes.js';
+export { registerServerComponent, registerServerProvider, serverComponent, serverComponents, serverProvider, } from './registry.js';
+//# sourceMappingURL=index.js.map

package/dist/view/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/view/index.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,wFAAwF;AACxF,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,gBAAgB,EAAE,UAAU,EAAuB,MAAM,eAAe,CAAC;AAClG,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,OAAO,EAAiB,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAsB,MAAM,sBAAsB,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAWlE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACtC,OAAO,EAAE,OAAO,EAAoD,MAAM,oBAAoB,CAAC;AAC/F,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,EACL,GAAG,EACH,aAAa,EACb,SAAS,EACT,UAAU,GAIX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACpF,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,cAAc,GAKf,MAAM,eAAe,CAAC","sourcesContent":["// The view layer's entry point for the rest of core (ADR 0018 \"Where it lives\"): code outside\n// view/ imports only this module. @gyral/core's index re-exports the public part of it.\nexport { DEV } from '#view-dev';\nexport { html, compiled, isTemplateResult, templateOf, type TemplateResult } from './template.js';\nexport { templateElement } from './template-element.js';\nexport { normalize, analyze, type Analysis } from './normalize/normalize.js';\nexport { checkTemplate, type TemplateIssue } from './normalize/check.js';\nexport { templateId } from './normalize/id.js';\nexport { TemplateError } from './normalize/errors.js';\nexport { shapeMismatch, repairError } from './normalize/shape.js';\nexport type {\n  NormalizedTemplate,\n  PartSpec,\n  Path,\n  Segment,\n  Shape,\n  ShapeNode,\n  TemplateObject,\n} from './normalize/types.js';\n\nexport { hydrate } from './render/hydrate.js';\nexport { render, renderBatch } from './render/render.js';\nexport type { Markup, SeenMarkup } from './render/seen.js';\nexport { HydrationMismatch } from './render/mismatch.js';\nexport { each } from './render/list.js';\nexport { raw } from './render/raw.js';\nexport { nothing, type ChildValue, type ListResult, type RawResult } from './render/values.js';\nexport { defineHook } from './render/hook-part.js';\nexport type { HookAttributes, HookResult, HookSpec } from './render/hooks.js';\nexport {\n  css,\n  isStyleSource,\n  sheetsFor,\n  styleTexts,\n  type CssValue,\n  type StyleSource,\n  type Styles,\n} from './styles.js';\nexport { ISLAND_ATTRIBUTE, LIGHT_ATTRIBUTE, SEED_ATTRIBUTE } from './attributes.js';\nexport {\n  registerServerComponent,\n  registerServerProvider,\n  serverComponent,\n  serverComponents,\n  serverProvider,\n  type ServerComponent,\n  type ServerProvider,\n  type ServerRenderInput,\n  type ServerRendering,\n} from './registry.js';\n"]}

package/dist/view/normalize/check.d.ts

@@ -0,0 +1,20 @@
+import { TemplateError } from './errors.js';
+/** A position in the minified strings: string index, offset in that string. */
+export type At = readonly [index: number, offset: number];
+/** A template's first rule violation, and where the normalizer was when it found it. */
+export interface TemplateIssue {
+    /** The same error `normalize(strings)` throws. */
+    readonly error: TemplateError;
+    /** The whitespace-minified strings the rules read (as many as the input). */
+    readonly strings: readonly string[];
+    /** Where reading stopped. */
+    readonly at: At;
+    /**
+     * Where the token the error is about starts, when the tree builder found it in a tag, an end
+     * tag or a run of text (the token ends at `at`). Undefined when the tokenizer found it at
+     * `at` itself, or at a child hole (then `at` is the end of the string before the hole).
+     */
+    readonly from: At | undefined;
+}
+/** The template's first rule violation, or undefined when `normalize` would accept it. */
+export declare function checkTemplate(strings: readonly string[]): TemplateIssue | undefined;

package/dist/view/normalize/check.js

@@ -0,0 +1,78 @@
+// The template rules (view/09-template-rules.md) as a check that reports where it stopped, for
+// tools that point at the markup (the ESLint plugin, @gyral/core/eslint). It runs the same
+// steps as `analyze` (normalize.ts) up to the last one that can fail: minify whitespace, then
+// tokenize and build the tree (emit and the id never throw). Like the compiler and the runtime,
+// it stops at a template's first error: the tokenizer can't recover from one.
+import { TemplateError } from './errors.js';
+import { Source } from './source.js';
+import { tokenize } from './tokenizer.js';
+import { TreeBuilder } from './tree.js';
+import { minifyStrings } from './whitespace.js';
+/** Forwards tokens to the tree builder, remembering where the current token started. */
+class Tracker {
+    constructor(src, tree) {
+        this.src = src;
+        this.tree = tree;
+        this.mark = [0, 0];
+    }
+    /** A token starts at `mark`; an error before `after` is about it (a child hole: the hole). */
+    before(about = true) {
+        this.from = about ? this.mark : undefined;
+    }
+    after() {
+        this.from = undefined;
+        this.mark = [this.src.i, this.src.pos];
+    }
+    text(raw) {
+        this.before();
+        this.tree.text(raw);
+        this.after();
+    }
+    comment(raw) {
+        this.before();
+        this.tree.comment(raw);
+        this.after();
+    }
+    doctype(raw) {
+        this.before();
+        this.tree.doctype(raw);
+        this.after();
+    }
+    start(tag) {
+        this.before();
+        const mode = this.tree.start(tag);
+        this.after();
+        return mode;
+    }
+    end(name) {
+        this.before();
+        this.tree.end(name);
+        this.after();
+    }
+    hole(kind) {
+        this.before(false);
+        this.tree.hole(kind);
+        this.after();
+    }
+    finish() {
+        this.before();
+        this.tree.finish();
+        this.after();
+    }
+}
+/** The template's first rule violation, or undefined when `normalize` would accept it. */
+export function checkTemplate(strings) {
+    const normalized = minifyStrings(strings);
+    const src = new Source(normalized, undefined);
+    const tracker = new Tracker(src, new TreeBuilder(src));
+    try {
+        tokenize(src, tracker);
+    }
+    catch (error) {
+        if (!(error instanceof TemplateError))
+            throw error;
+        return { error, strings: normalized, at: [src.i, src.pos], from: tracker.from };
+    }
+    return undefined;
+}
+//# sourceMappingURL=check.js.map

package/dist/view/normalize/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../../src/view/normalize/check.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,2FAA2F;AAC3F,8FAA8F;AAC9F,gGAAgG;AAChG,8EAA8E;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAA8C,MAAM,gBAAgB,CAAC;AACtF,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAqBhD,wFAAwF;AACxF,MAAM,OAAO;IAIX,YACmB,GAAW,EACX,IAAiB;QADjB,QAAG,GAAH,GAAG,CAAQ;QACX,SAAI,GAAJ,IAAI,CAAa;QALpC,SAAI,GAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAMf,CAAC;IAEJ,8FAA8F;IACtF,MAAM,CAAC,KAAK,GAAG,IAAI;QACzB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5C,CAAC;IAEO,KAAK;QACX,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzC,CAAC;IAED,IAAI,CAAC,GAAW;QACd,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IACD,OAAO,CAAC,GAAW;QACjB,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IACD,OAAO,CAAC,GAAW;QACjB,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IACD,KAAK,CAAC,GAAa;QACjB,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IACD,GAAG,CAAC,IAAY;QACd,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpB,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IACD,IAAI,CAAC,IAAsB;QACzB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACnB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrB,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IACD,MAAM;QACJ,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QACnB,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;CACF;AAED,0FAA0F;AAC1F,MAAM,UAAU,aAAa,CAAC,OAA0B;IACtD,MAAM,UAAU,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IACvD,IAAI,CAAC;QACH,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,aAAa,CAAC;YAAE,MAAM,KAAK,CAAC;QACnD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;IAClF,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["// The template rules (view/09-template-rules.md) as a check that reports where it stopped, for\n// tools that point at the markup (the ESLint plugin, @gyral/core/eslint). It runs the same\n// steps as `analyze` (normalize.ts) up to the last one that can fail: minify whitespace, then\n// tokenize and build the tree (emit and the id never throw). Like the compiler and the runtime,\n// it stops at a template's first error: the tokenizer can't recover from one.\nimport { TemplateError } from './errors.js';\nimport { Source } from './source.js';\nimport { tokenize, type ContentMode, type Sink, type StartTag } from './tokenizer.js';\nimport { TreeBuilder } from './tree.js';\nimport { minifyStrings } from './whitespace.js';\n\n/** A position in the minified strings: string index, offset in that string. */\nexport type At = readonly [index: number, offset: number];\n\n/** A template's first rule violation, and where the normalizer was when it found it. */\nexport interface TemplateIssue {\n  /** The same error `normalize(strings)` throws. */\n  readonly error: TemplateError;\n  /** The whitespace-minified strings the rules read (as many as the input). */\n  readonly strings: readonly string[];\n  /** Where reading stopped. */\n  readonly at: At;\n  /**\n   * Where the token the error is about starts, when the tree builder found it in a tag, an end\n   * tag or a run of text (the token ends at `at`). Undefined when the tokenizer found it at\n   * `at` itself, or at a child hole (then `at` is the end of the string before the hole).\n   */\n  readonly from: At | undefined;\n}\n\n/** Forwards tokens to the tree builder, remembering where the current token started. */\nclass Tracker implements Sink {\n  mark: At = [0, 0];\n  from: At | undefined;\n\n  constructor(\n    private readonly src: Source,\n    private readonly tree: TreeBuilder,\n  ) {}\n\n  /** A token starts at `mark`; an error before `after` is about it (a child hole: the hole). */\n  private before(about = true): void {\n    this.from = about ? this.mark : undefined;\n  }\n\n  private after(): void {\n    this.from = undefined;\n    this.mark = [this.src.i, this.src.pos];\n  }\n\n  text(raw: string): void {\n    this.before();\n    this.tree.text(raw);\n    this.after();\n  }\n  comment(raw: string): void {\n    this.before();\n    this.tree.comment(raw);\n    this.after();\n  }\n  doctype(raw: string): void {\n    this.before();\n    this.tree.doctype(raw);\n    this.after();\n  }\n  start(tag: StartTag): ContentMode {\n    this.before();\n    const mode = this.tree.start(tag);\n    this.after();\n    return mode;\n  }\n  end(name: string): void {\n    this.before();\n    this.tree.end(name);\n    this.after();\n  }\n  hole(kind: 'child' | 'text'): void {\n    this.before(false);\n    this.tree.hole(kind);\n    this.after();\n  }\n  finish(): void {\n    this.before();\n    this.tree.finish();\n    this.after();\n  }\n}\n\n/** The template's first rule violation, or undefined when `normalize` would accept it. */\nexport function checkTemplate(strings: readonly string[]): TemplateIssue | undefined {\n  const normalized = minifyStrings(strings);\n  const src = new Source(normalized, undefined);\n  const tracker = new Tracker(src, new TreeBuilder(src));\n  try {\n    tokenize(src, tracker);\n  } catch (error) {\n    if (!(error instanceof TemplateError)) throw error;\n    return { error, strings: normalized, at: [src.i, src.pos], from: tracker.from };\n  }\n  return undefined;\n}\n"]}

package/dist/view/normalize/emit.d.ts

@@ -0,0 +1,13 @@
+import type { TreeNode } from './tree.js';
+import { type PartSpec, type Segment, type Shape } from './types.js';
+export interface Emitted {
+    readonly html: string;
+    readonly parts: PartSpec[];
+    readonly segments: Segment[];
+    readonly shape: Shape;
+}
+/**
+ * Emits the HTML, part table, segments and shape for a template's tree. A `server` template
+ * (a page shell) gets no anchors: hydration never walks it, and the browser never renders it.
+ */
+export declare function emit(root: readonly TreeNode[], server: boolean): Emitted;