@gyral/core 0.2.0 → 0.3.1

package/dist/host-model.js

@@ -0,0 +1,278 @@
+// The model side of one Gyral host (docs/design-docs/view/05-element.md, ADR 0006, ADR 0013):
+// state, reducers and commands. element.ts owns the DOM side (props, root, lifecycle,
+// rendering) and asks this object for state and context. Reducers run at once, so `state` is
+// always current; only the render waits (04). The interpreter and the store binding come from
+// features.ts, registered by `command()` and `defineStore()`; marker drivers (focus, emit, store
+// sends) carry their own `local` handler.
+import { DEVTOOLS_ENABLED, devCommands, devOwner, devUpdate } from '#devtools';
+import { splitNext } from './command.js';
+import { features, } from './features.js';
+import { fail } from './errors.js';
+import { runInit } from './init.js';
+import { noteActivity, requestTransition } from './scheduler.js';
+import { errored, subscriptions as subscriptionSet } from '#spec-features';
+import { message } from './view/index.js';
+export class HostModel {
+    #host;
+    #spec;
+    #reducers;
+    #binding;
+    #model;
+    /** Props as of init or the last PropsChanged: the `prev` of the next PropsChanged. */
+    #seen;
+    #interpreter;
+    /** Commands kept while disconnected (init's, before the first connect); undefined once connected. */
+    #pending;
+    /** Connected to the document (a pending stop checks it, so a move cancels the stop). */
+    #on;
+    /** `spec.subscriptions`, kept running once the host has rendered (ADR 0025). */
+    #subs;
+    /** `init` threw (ADR 0024): the host shows its error view, or stays empty. */
+    #failure;
+    /** Handling `Errored`: a failure now is reported, never sent again (no loops). */
+    #erroring;
+    constructor(host, spec) {
+        /** Commands kept while disconnected (init's, before the first connect); undefined once connected. */
+        this.#pending = [];
+        /** Connected to the document (a pending stop checks it, so a move cancels the stop). */
+        this.#on = false;
+        /** Handling `Errored`: a failure now is reported, never sent again (no loops). */
+        this.#erroring = false;
+        /** The store binding, created on first use. Only reached once `defineStore()` has run. */
+        this.stores = () => (this.#binding ??= features.stores(this.#host.el, this.#host.tag, this.#spec.stores ?? [], (store, state, prev) => {
+            this.#storeChanged(store, state, prev);
+        }));
+        this.#host = host;
+        this.el = host.el;
+        this.tag = host.tag;
+        this.root = host.root;
+        this.#spec = spec;
+        // Sound: dispatch() only calls the reducer whose key equals msg._tag. A component without
+        // messages may have no `update` (its spec type is widened to Tagged here).
+        this.#reducers = (spec.update ?? {});
+    }
+    get ready() {
+        return this.#model !== undefined;
+    }
+    /** Set when `init` threw; the host has no state then. */
+    get failure() {
+        return this.#failure;
+    }
+    /** The current state, running `init` (and `initialMessages`) on first read. */
+    state(initialMessages = []) {
+        if (this.#model === undefined) {
+            this.#seen = this.#host.props();
+            const next = this.#init();
+            if (next === undefined)
+                return undefined; // init threw: `failure` says so
+            this.apply(next);
+            for (const msg of initialMessages)
+                this.dispatch(msg, false);
+        }
+        return this.#model.value;
+    }
+    /** `init(props)`, or undefined after reporting its failure (ADR 0024). */
+    #init() {
+        try {
+            return runInit(this.#spec, this.#seen);
+        }
+        catch (cause) {
+            this.#failure = this.fail(cause, 'init', message(74, this.tag));
+            this.#model = { value: undefined };
+            return undefined;
+        }
+    }
+    /**
+     * Reports a failure of this host (ADR 0024) and, for a failed update, parse or command, sends
+     * `Errored` to its optional reducer. A failure while handling `Errored` is only reported.
+     */
+    fail(cause, phase, text, msg) {
+        const error = fail(cause, phase, text, { host: this.el, tag: this.tag, msg });
+        if (!this.#erroring && errored !== undefined && this.#reducers['Errored'] !== undefined) {
+            this.#erroring = true;
+            try {
+                errored((msg) => this.dispatch(msg), phase, error);
+            }
+            finally {
+                this.#erroring = false;
+            }
+        }
+        return error;
+    }
+    hasReducer(tag) {
+        return this.#reducers[tag] !== undefined;
+    }
+    /**
+     * Resumes from a server seed (ADR 0012): the server's state, or `init(props)`'s when the
+     * seed left it out. Returns init's commands, to start after the first render.
+     */
+    resume(seed) {
+        this.#seen = this.#host.props();
+        const next = this.#init();
+        if (next === undefined)
+            return [];
+        const [initial, commands] = splitNext(next);
+        // Sound: the seed is this component's own state, written by the server.
+        this.#model = { value: 'state' in seed ? seed.state : initial };
+        return commands;
+    }
+    /**
+     * PropsChanged when props differ from the last ones seen (`Object.is` per prop). A reducer
+     * that throws leaves them unseen, so the next render sends PropsChanged again (ADR 0024).
+     */
+    syncProps(names) {
+        const prev = this.#seen;
+        if (prev === undefined || this.#failure !== undefined)
+            return;
+        const props = this.#host.props();
+        if (names.every((name) => Object.is(props[name], prev[name])))
+            return;
+        if (this.dispatch({ _tag: 'PropsChanged', props, prev }, false))
+            this.#seen = props;
+        this.#resubscribe();
+    }
+    /**
+     * Runs `msg`'s reducer. A reducer that throws changes nothing (no state, no commands): the
+     * failure is reported (ADR 0024) and dispatch returns false.
+     */
+    dispatch(msg, schedule = true) {
+        noteActivity(); // settled() keeps waiting while messages arrive (04)
+        const reducer = this.#reducers[msg._tag];
+        if (reducer === undefined) {
+            // Framework messages have optional reducers; props and stores stay readable as context.
+            if (msg._tag !== 'PropsChanged' && msg._tag !== 'StoreChanged' && msg._tag !== 'Errored') {
+                console.warn(message(10, this.#host.tag, msg._tag));
+            }
+            return true;
+        }
+        if (this.#failure !== undefined)
+            return false;
+        const prev = this.state();
+        let next;
+        try {
+            next = reducer(prev, msg, this.ctx());
+        }
+        catch (cause) {
+            this.fail(cause, 'update', message(73, this.tag, msg._tag), msg._tag);
+            return false;
+        }
+        this.apply(next);
+        const state = this.state();
+        if (DEVTOOLS_ENABLED)
+            devUpdate(this.#host.el, this.#host.tag, msg, prev, state);
+        this.#resubscribe();
+        if (!schedule)
+            return true;
+        if (this.#spec.viewTransition?.(prev, state, msg) === true)
+            requestTransition();
+        this.#host.invalidate(this.#onFrame(msg._tag));
+        return true;
+    }
+    apply(next) {
+        const [state, commands] = splitNext(next);
+        this.#model = { value: state };
+        for (const cmd of commands) {
+            const local = cmd.driver.local;
+            if (local !== undefined)
+                local(this, cmd.input);
+            else if (this.#pending !== undefined)
+                this.#pending.push(cmd);
+            else
+                this.#commands().run(cmd);
+        }
+    }
+    /** Starts commands kept for later (init's, after a server-rendered host's first render). */
+    run(commands) {
+        this.apply([this.state(), commands]);
+    }
+    // Reducers and the view get this too; only parsers' type (ParserCtx) names `state`.
+    ctx() {
+        return {
+            props: this.#host.props(),
+            read: (store) => this.stores().read(store),
+            state: this.state(),
+        };
+    }
+    /**
+     * Resolves stores and runs kept commands; after a real detach, starts the subscriptions again
+     * (05 "Lifecycle"). Returns true if store instances were bound.
+     */
+    connect() {
+        this.#on = true; // a move: the pending stop finds the host connected and does nothing
+        // The nearest <gyral-stores> may differ after a move.
+        const rebound = (this.#spec.stores?.length ?? 0) > 0 && this.stores().connect();
+        const pending = this.#pending ?? [];
+        this.#pending = undefined;
+        for (const cmd of pending)
+            this.#commands().run(cmd);
+        this.#resubscribe(); // a move: unchanged, nothing restarts
+        return rebound;
+    }
+    /**
+     * Starts `spec.subscriptions` (ADR 0025): after the first render, as init's commands of a
+     * server-rendered host are, so nothing they emit can change what hydration adopts.
+     */
+    subscribe() {
+        const derive = this.#spec.subscriptions;
+        if (derive === undefined || subscriptionSet === undefined)
+            return;
+        this.#subs ??= subscriptionSet(this, derive);
+        this.#resubscribe();
+    }
+    /** Aborts the running command of `lane` (a subscription that left, ADR 0025). */
+    cancel(lane) {
+        this.#interpreter?.cancel(lane);
+    }
+    /** Syncs the subscriptions while connected and healthy. */
+    #resubscribe() {
+        if (this.#pending === undefined && this.#failure === undefined)
+            this.#subs?.update();
+    }
+    /**
+     * Stops the commands one microtask later, unless the host is connected again first: a move
+     * (`appendChild`, `insertBefore`) disconnects and connects in one task and keeps them running.
+     */
+    disconnect() {
+        this.#binding?.disconnect();
+        this.#pending ??= [];
+        this.#on = false;
+        queueMicrotask(() => {
+            if (this.#on)
+                return;
+            this.#interpreter?.dispose();
+            this.#interpreter = undefined;
+            this.#subs?.reset();
+        });
+    }
+    /**
+     * The interpreter, started with the first command after connecting. Only reached for a
+     * command built by `command()`, which registered it (features.ts).
+     */
+    #commands() {
+        const el = this.el;
+        return (this.#interpreter ??= features.commands(el, (msg) => {
+            this.dispatch(msg);
+        }, DEVTOOLS_ENABLED ? devCommands(() => devOwner(el, this.tag)) : undefined, (cause, code, driver) => {
+            const owner = `<${this.tag}>`;
+            const text = code === 40
+                ? message(40, owner, driver)
+                : code === 41
+                    ? message(41, owner, driver)
+                    : message(43, owner, driver);
+            this.fail(cause, 'command', text, driver);
+        }));
+    }
+    /** Does `tag` render in the frame lane (`spec.renderOnFrame`)? */
+    #onFrame(tag) {
+        return this.#spec.renderOnFrame?.includes(tag) === true;
+    }
+    #storeChanged(store, state, prev) {
+        if (this.#reducers['StoreChanged'] !== undefined) {
+            this.dispatch({ _tag: 'StoreChanged', store: store.name, state, prev });
+        }
+        else {
+            this.#host.invalidate(this.#onFrame('StoreChanged'));
+        }
+    }
+}
+//# sourceMappingURL=host-model.js.map

package/dist/host-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-model.js","sourceRoot":"","sources":["../src/host-model.ts"],"names":[],"mappings":"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","sourcesContent":["// The model side of one Gyral host (docs/design-docs/view/05-element.md, ADR 0006, ADR 0013):\n// state, reducers and commands. element.ts owns the DOM side (props, root, lifecycle,\n// rendering) and asks this object for state and context. Reducers run at once, so `state` is\n// always current; only the render waits (04). The interpreter and the store binding come from\n// features.ts, registered by `command()` and `defineStore()`; marker drivers (focus, emit, store\n// sends) carry their own `local` handler.\nimport { DEVTOOLS_ENABLED, devCommands, devOwner, devUpdate } from '#devtools';\nimport { splitNext, type Command, type Next } from './command.js';\nimport {\n  features,\n  type FeatureHost,\n  type LocalDriver,\n  type LocalHost,\n  type StoreLink,\n} from './features.js';\nimport { fail, type ErrorPhase, type GyralError } from './errors.js';\nimport type { Seed } from './hydration.js';\nimport { runInit } from './init.js';\nimport type { Interpreter } from './internal/interpreter.js';\nimport { noteActivity, requestTransition } from './scheduler.js';\nimport { errored, subscriptions as subscriptionSet } from '#spec-features';\nimport type { Subscriptions } from './subscriptions.js';\nimport type { AnyStore } from './store.js';\nimport type { ComponentSpec, Ctx, IntentRejected, ParserCtx, Tagged } from './types.js';\nimport { message } from './view/index.js';\n\ntype Bag = Readonly<Record<string, unknown>>;\ntype Reducer<S> = (state: S, msg: Tagged, ctx: Ctx<object>) => Next<S, Tagged>;\n/** A command as the model runs it. */\nexport type ModelCommand = Command<Tagged | IntentRejected>;\ntype Cmd = ModelCommand;\n\n/** What the model needs from its element. */\nexport interface ModelHost {\n  readonly el: FeatureHost;\n  readonly tag: string;\n  /** The declared props as components see them (defaults applied). */\n  readonly props: () => Bag;\n  /** The host's root once it has one (focus commands run against it). */\n  readonly root: () => ParentNode | undefined;\n  /** Something changed that the next render must show; `onFrame`: in the frame lane (04). */\n  readonly invalidate: (onFrame: boolean) => void;\n}\n\nexport class HostModel<S, P> implements LocalHost {\n  readonly el: FeatureHost;\n  readonly tag: string;\n  readonly root: () => ParentNode | undefined;\n  readonly #host: ModelHost;\n  readonly #spec: ComponentSpec<S, Tagged, P>;\n  readonly #reducers: Readonly<Record<string, Reducer<S> | undefined>>;\n  #binding: StoreLink | undefined;\n  #model: { value: S } | undefined;\n  /** Props as of init or the last PropsChanged: the `prev` of the next PropsChanged. */\n  #seen: Bag | undefined;\n  #interpreter: Interpreter<Tagged | IntentRejected> | undefined;\n  /** Commands kept while disconnected (init's, before the first connect); undefined once connected. */\n  #pending: Cmd[] | undefined = [];\n  /** Connected to the document (a pending stop checks it, so a move cancels the stop). */\n  #on = false;\n  /** `spec.subscriptions`, kept running once the host has rendered (ADR 0025). */\n  #subs: Subscriptions | undefined;\n  /** `init` threw (ADR 0024): the host shows its error view, or stays empty. */\n  #failure: GyralError | undefined;\n  /** Handling `Errored`: a failure now is reported, never sent again (no loops). */\n  #erroring = false;\n\n  constructor(host: ModelHost, spec: ComponentSpec<S, Tagged, P>) {\n    this.#host = host;\n    this.el = host.el;\n    this.tag = host.tag;\n    this.root = host.root;\n    this.#spec = spec;\n    // Sound: dispatch() only calls the reducer whose key equals msg._tag. A component without\n    // messages may have no `update` (its spec type is widened to Tagged here).\n    this.#reducers = ((spec as { readonly update?: object }).update ?? {}) as unknown as Readonly<\n      Record<string, Reducer<S> | undefined>\n    >;\n  }\n\n  /** The store binding, created on first use. Only reached once `defineStore()` has run. */\n  readonly stores = (): StoreLink =>\n    (this.#binding ??= (features.stores as NonNullable<typeof features.stores>)(\n      this.#host.el,\n      this.#host.tag,\n      this.#spec.stores ?? [],\n      (store, state, prev) => {\n        this.#storeChanged(store, state, prev);\n      },\n    ));\n\n  get ready(): boolean {\n    return this.#model !== undefined;\n  }\n\n  /** Set when `init` threw; the host has no state then. */\n  get failure(): GyralError | undefined {\n    return this.#failure;\n  }\n\n  /** The current state, running `init` (and `initialMessages`) on first read. */\n  state(initialMessages: readonly Tagged[] = []): S {\n    if (this.#model === undefined) {\n      this.#seen = this.#host.props();\n      const next = this.#init();\n      if (next === undefined) return undefined as S; // init threw: `failure` says so\n      this.apply(next);\n      for (const msg of initialMessages) this.dispatch(msg, false);\n    }\n    return (this.#model as { value: S }).value;\n  }\n\n  /** `init(props)`, or undefined after reporting its failure (ADR 0024). */\n  #init(): Next<S, Tagged> | undefined {\n    try {\n      return runInit(this.#spec, this.#seen as P);\n    } catch (cause) {\n      this.#failure = this.fail(cause, 'init', message(74, this.tag));\n      this.#model = { value: undefined as S };\n      return undefined;\n    }\n  }\n\n  /**\n   * Reports a failure of this host (ADR 0024) and, for a failed update, parse or command, sends\n   * `Errored` to its optional reducer. A failure while handling `Errored` is only reported.\n   */\n  fail(cause: unknown, phase: ErrorPhase, text: string, msg?: string): GyralError {\n    const error = fail(cause, phase, text, { host: this.el, tag: this.tag, msg });\n    if (!this.#erroring && errored !== undefined && this.#reducers['Errored'] !== undefined) {\n      this.#erroring = true;\n      try {\n        errored((msg) => this.dispatch(msg), phase, error);\n      } finally {\n        this.#erroring = false;\n      }\n    }\n    return error;\n  }\n\n  hasReducer(tag: string): boolean {\n    return this.#reducers[tag] !== undefined;\n  }\n\n  /**\n   * Resumes from a server seed (ADR 0012): the server's state, or `init(props)`'s when the\n   * seed left it out. Returns init's commands, to start after the first render.\n   */\n  resume(seed: Seed): readonly Cmd[] {\n    this.#seen = this.#host.props();\n    const next = this.#init();\n    if (next === undefined) return [];\n    const [initial, commands] = splitNext(next);\n    // Sound: the seed is this component's own state, written by the server.\n    this.#model = { value: 'state' in seed ? (seed.state as S) : initial };\n    return commands;\n  }\n\n  /**\n   * PropsChanged when props differ from the last ones seen (`Object.is` per prop). A reducer\n   * that throws leaves them unseen, so the next render sends PropsChanged again (ADR 0024).\n   */\n  syncProps(names: readonly string[]): void {\n    const prev = this.#seen;\n    if (prev === undefined || this.#failure !== undefined) return;\n    const props = this.#host.props();\n    if (names.every((name) => Object.is(props[name], prev[name]))) return;\n    if (this.dispatch({ _tag: 'PropsChanged', props, prev } as Tagged, false)) this.#seen = props;\n    this.#resubscribe();\n  }\n\n  /**\n   * Runs `msg`'s reducer. A reducer that throws changes nothing (no state, no commands): the\n   * failure is reported (ADR 0024) and dispatch returns false.\n   */\n  dispatch(msg: Tagged, schedule = true): boolean {\n    noteActivity(); // settled() keeps waiting while messages arrive (04)\n    const reducer = this.#reducers[msg._tag];\n    if (reducer === undefined) {\n      // Framework messages have optional reducers; props and stores stay readable as context.\n      if (msg._tag !== 'PropsChanged' && msg._tag !== 'StoreChanged' && msg._tag !== 'Errored') {\n        console.warn(message(10, this.#host.tag, msg._tag));\n      }\n      return true;\n    }\n    if (this.#failure !== undefined) return false;\n    const prev = this.state();\n    let next: Next<S, Tagged>;\n    try {\n      next = reducer(prev, msg, this.ctx() as Ctx<object>);\n    } catch (cause) {\n      this.fail(cause, 'update', message(73, this.tag, msg._tag), msg._tag);\n      return false;\n    }\n    this.apply(next);\n    const state = this.state();\n    if (DEVTOOLS_ENABLED) devUpdate(this.#host.el, this.#host.tag, msg, prev, state);\n    this.#resubscribe();\n    if (!schedule) return true;\n    if (this.#spec.viewTransition?.(prev, state, msg) === true) requestTransition();\n    this.#host.invalidate(this.#onFrame(msg._tag));\n    return true;\n  }\n\n  apply(next: Next<S, Tagged> | Next<S, Tagged | IntentRejected>): void {\n    const [state, commands] = splitNext(next as Next<S, Tagged>);\n    this.#model = { value: state };\n    for (const cmd of commands as readonly Cmd[]) {\n      const local = (cmd.driver as Partial<LocalDriver>).local;\n      if (local !== undefined) local(this, cmd.input);\n      else if (this.#pending !== undefined) this.#pending.push(cmd);\n      else this.#commands().run(cmd);\n    }\n  }\n\n  /** Starts commands kept for later (init's, after a server-rendered host's first render). */\n  run(commands: readonly Cmd[]): void {\n    this.apply([this.state(), commands]);\n  }\n\n  // Reducers and the view get this too; only parsers' type (ParserCtx) names `state`.\n  ctx(): ParserCtx<P, S> {\n    return {\n      props: this.#host.props() as P,\n      read: (store) => this.stores().read(store),\n      state: this.state(),\n    };\n  }\n\n  /**\n   * Resolves stores and runs kept commands; after a real detach, starts the subscriptions again\n   * (05 \"Lifecycle\"). Returns true if store instances were bound.\n   */\n  connect(): boolean {\n    this.#on = true; // a move: the pending stop finds the host connected and does nothing\n    // The nearest <gyral-stores> may differ after a move.\n    const rebound = (this.#spec.stores?.length ?? 0) > 0 && this.stores().connect();\n    const pending = this.#pending ?? [];\n    this.#pending = undefined;\n    for (const cmd of pending) this.#commands().run(cmd);\n    this.#resubscribe(); // a move: unchanged, nothing restarts\n    return rebound;\n  }\n\n  /**\n   * Starts `spec.subscriptions` (ADR 0025): after the first render, as init's commands of a\n   * server-rendered host are, so nothing they emit can change what hydration adopts.\n   */\n  subscribe(): void {\n    const derive = this.#spec.subscriptions;\n    if (derive === undefined || subscriptionSet === undefined) return;\n    this.#subs ??= subscriptionSet(this, derive);\n    this.#resubscribe();\n  }\n\n  /** Aborts the running command of `lane` (a subscription that left, ADR 0025). */\n  cancel(lane: string): void {\n    this.#interpreter?.cancel(lane);\n  }\n\n  /** Syncs the subscriptions while connected and healthy. */\n  #resubscribe(): void {\n    if (this.#pending === undefined && this.#failure === undefined) this.#subs?.update();\n  }\n\n  /**\n   * Stops the commands one microtask later, unless the host is connected again first: a move\n   * (`appendChild`, `insertBefore`) disconnects and connects in one task and keeps them running.\n   */\n  disconnect(): void {\n    this.#binding?.disconnect();\n    this.#pending ??= [];\n    this.#on = false;\n    queueMicrotask(() => {\n      if (this.#on) return;\n      this.#interpreter?.dispose();\n      this.#interpreter = undefined;\n      this.#subs?.reset();\n    });\n  }\n\n  /**\n   * The interpreter, started with the first command after connecting. Only reached for a\n   * command built by `command()`, which registered it (features.ts).\n   */\n  #commands(): Interpreter<Tagged | IntentRejected> {\n    const el = this.el;\n    return (this.#interpreter ??= (features.commands as NonNullable<typeof features.commands>)(\n      el,\n      (msg) => {\n        this.dispatch(msg);\n      },\n      DEVTOOLS_ENABLED ? devCommands(() => devOwner(el, this.tag)) : undefined,\n      (cause, code, driver) => {\n        const owner = `<${this.tag}>`;\n        const text =\n          code === 40\n            ? message(40, owner, driver)\n            : code === 41\n              ? message(41, owner, driver)\n              : message(43, owner, driver);\n        this.fail(cause, 'command', text, driver);\n      },\n    ));\n  }\n\n  /** Does `tag` render in the frame lane (`spec.renderOnFrame`)? */\n  #onFrame(tag: string): boolean {\n    return this.#spec.renderOnFrame?.includes(tag) === true;\n  }\n\n  #storeChanged(store: AnyStore, state: unknown, prev: unknown): void {\n    if (this.#reducers['StoreChanged'] !== undefined) {\n      this.dispatch({ _tag: 'StoreChanged', store: store.name, state, prev } as Tagged);\n    } else {\n      this.#host.invalidate(this.#onFrame('StoreChanged'));\n    }\n  }\n}\n"]}

package/dist/hydration-client.d.ts

@@ -0,0 +1,9 @@
+import { type ChildValue, type SeenMarkup } from './view/index.js';
+export { scheduleIsland } from './islands.js';
+/**
+ * Hydrates a server-rendered host's root with its first view (view/07-hydration.md "Steps").
+ * A shadow root swaps styles in the same step (08 "Hydration"): the shared sheets are adopted
+ * and the server's `<style>` removed. On a mismatch development throws; production recovers
+ * this component only: it clears the root, renders fresh and warns.
+ */
+export declare function hydrateRoot(host: HTMLElement, tag: string, view: ChildValue, root: ShadowRoot | HTMLElement, sheets: CSSStyleSheet[] | undefined, seen: SeenMarkup): void;

package/dist/hydration-client.js

@@ -0,0 +1,35 @@
+// The lazily loaded half of hydration (view/07-hydration.md "Loading"): the parallel walk and
+// islands. element.ts imports this module with import() when the first host that needs it
+// connects (one with a seed or `defer-hydration`), so client-only pages never fetch it.
+import { DEVTOOLS_ENABLED, devMismatch } from '#devtools';
+import { DEV, hydrate, HydrationMismatch, message, render, } from './view/index.js';
+export { scheduleIsland } from './islands.js';
+/**
+ * Hydrates a server-rendered host's root with its first view (view/07-hydration.md "Steps").
+ * A shadow root swaps styles in the same step (08 "Hydration"): the shared sheets are adopted
+ * and the server's `<style>` removed. On a mismatch development throws; production recovers
+ * this component only: it clears the root, renders fresh and warns.
+ */
+export function hydrateRoot(host, tag, view, root, sheets, seen) {
+    if (sheets !== undefined) {
+        root.adoptedStyleSheets = sheets;
+        const first = root.firstChild;
+        if (sheets.length > 0 && first?.nodeName === 'STYLE')
+            first.remove();
+    }
+    try {
+        hydrate(view, root, `<${tag}>`, seen);
+    }
+    catch (error) {
+        if (!(error instanceof HydrationMismatch))
+            throw error;
+        if (DEVTOOLS_ENABLED)
+            devMismatch(host, tag, error.message);
+        if (DEV)
+            throw error;
+        console.warn(message(63, tag), error.message);
+        root.replaceChildren();
+        render(view, root, seen);
+    }
+}
+//# sourceMappingURL=hydration-client.js.map

package/dist/hydration-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydration-client.js","sourceRoot":"","sources":["../src/hydration-client.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,0FAA0F;AAC1F,wFAAwF;AACxF,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EACL,GAAG,EACH,OAAO,EACP,iBAAiB,EACjB,OAAO,EACP,MAAM,GAGP,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,IAAiB,EACjB,GAAW,EACX,IAAgB,EAChB,IAA8B,EAC9B,MAAmC,EACnC,IAAgB;IAEhB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACxB,IAAmB,CAAC,kBAAkB,GAAG,MAAM,CAAC;QACjD,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC;QAC9B,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,EAAE,QAAQ,KAAK,OAAO;YAAE,KAAK,CAAC,MAAM,EAAE,CAAC;IACvE,CAAC;IACD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,GAAG,EAAE,IAAI,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,iBAAiB,CAAC;YAAE,MAAM,KAAK,CAAC;QACvD,IAAI,gBAAgB;YAAE,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5D,IAAI,GAAG;YAAE,MAAM,KAAK,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC","sourcesContent":["// The lazily loaded half of hydration (view/07-hydration.md \"Loading\"): the parallel walk and\n// islands. element.ts imports this module with import() when the first host that needs it\n// connects (one with a seed or `defer-hydration`), so client-only pages never fetch it.\nimport { DEVTOOLS_ENABLED, devMismatch } from '#devtools';\nimport {\n  DEV,\n  hydrate,\n  HydrationMismatch,\n  message,\n  render,\n  type ChildValue,\n  type SeenMarkup,\n} from './view/index.js';\n\nexport { scheduleIsland } from './islands.js';\n\n/**\n * Hydrates a server-rendered host's root with its first view (view/07-hydration.md \"Steps\").\n * A shadow root swaps styles in the same step (08 \"Hydration\"): the shared sheets are adopted\n * and the server's `<style>` removed. On a mismatch development throws; production recovers\n * this component only: it clears the root, renders fresh and warns.\n */\nexport function hydrateRoot(\n  host: HTMLElement,\n  tag: string,\n  view: ChildValue,\n  root: ShadowRoot | HTMLElement,\n  sheets: CSSStyleSheet[] | undefined,\n  seen: SeenMarkup,\n): void {\n  if (sheets !== undefined) {\n    (root as ShadowRoot).adoptedStyleSheets = sheets;\n    const first = root.firstChild;\n    if (sheets.length > 0 && first?.nodeName === 'STYLE') first.remove();\n  }\n  try {\n    hydrate(view, root, `<${tag}>`, seen);\n  } catch (error) {\n    if (!(error instanceof HydrationMismatch)) throw error;\n    if (DEVTOOLS_ENABLED) devMismatch(host, tag, error.message);\n    if (DEV) throw error;\n    console.warn(message(63, tag), error.message);\n    root.replaceChildren();\n    render(view, root, seen);\n  }\n}\n"]}

package/dist/hydration-loader.d.ts

@@ -0,0 +1,13 @@
+import { type Seed } from './hydration.js';
+/** Client side: reads and removes the seed, if this element was server-rendered by Gyral. */
+export declare function takeSeed(host: Element): Seed | undefined;
+/**
+ * The walk and islands (hydration-client.ts) once loaded; `null` if loading failed (a stale
+ * deployment: server-rendered hosts then render fresh); undefined until then.
+ */
+export declare let hydrationCode: typeof import('./hydration-client.js') | null | undefined;
+/**
+ * Loads the hydration code (once) and runs `next` when it has loaded or failed, in call
+ * order. settled() waits meanwhile (view/07-hydration.md "Loading").
+ */
+export declare function whenHydrationLoads(next: () => void): void;

package/dist/hydration-loader.js

@@ -0,0 +1,58 @@
+// The client's half of seeds and hydration loading (view/07-hydration.md "Loading"), core's
+// `#hydration-loader`: reads a server-rendered host's seed on connect and loads the hydration
+// walk (hydration-client.ts) with import() when the first host that needs it connects.
+// Client-only builds (`gyralVitePreset({ clientOnly: true })`, gyral-c5d.11) resolve
+// `#hydration-loader` to hydration-off.ts instead: no import(), so no hydration chunk.
+import { SEED_ATTRIBUTE } from './hydration.js';
+import { hold } from './scheduler.js';
+import { message } from './view/index.js';
+/** Client side: reads and removes the seed, if this element was server-rendered by Gyral. */
+export function takeSeed(host) {
+    const raw = host.getAttribute(SEED_ATTRIBUTE);
+    if (raw === null)
+        return undefined;
+    host.removeAttribute(SEED_ATTRIBUTE);
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object')
+            return undefined;
+        const props = parsed.props ?? {};
+        return 'state' in parsed ? { state: parsed.state, props } : { props };
+    }
+    catch (error) {
+        console.error(message(60, host.localName, SEED_ATTRIBUTE), error);
+        return undefined;
+    }
+}
+/**
+ * The walk and islands (hydration-client.ts) once loaded; `null` if loading failed (a stale
+ * deployment: server-rendered hosts then render fresh); undefined until then.
+ */
+export let hydrationCode;
+/** Hosts waiting for the code, in connection order; undefined when no load is pending. */
+let waiting;
+/**
+ * Loads the hydration code (once) and runs `next` when it has loaded or failed, in call
+ * order. settled() waits meanwhile (view/07-hydration.md "Loading").
+ */
+export function whenHydrationLoads(next) {
+    if (waiting !== undefined) {
+        waiting.push(next);
+        return;
+    }
+    waiting = [next];
+    const done = (code) => {
+        hydrationCode = code;
+        const hosts = waiting ?? [];
+        waiting = undefined;
+        // Each in its own microtask, in order: one host throwing doesn't stop the others. They all
+        // run before `hold` counts the load as done.
+        for (const host of hosts)
+            queueMicrotask(host);
+    };
+    hold(import('./hydration-client.js').then(done, (error) => {
+        console.error(message(61), error);
+        done(null);
+    }));
+}
+//# sourceMappingURL=hydration-loader.js.map

package/dist/hydration-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydration-loader.js","sourceRoot":"","sources":["../src/hydration-loader.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,8FAA8F;AAC9F,uFAAuF;AACvF,qFAAqF;AACrF,uFAAuF;AACvF,OAAO,EAAE,cAAc,EAAa,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C,6FAA6F;AAC7F,MAAM,UAAU,QAAQ,CAAC,IAAa;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;IAC9C,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACnC,IAAI,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;IACrC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyB,CAAC;QACvD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACpE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;QACjC,OAAO,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;IACxE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,EAAE,KAAK,CAAC,CAAC;QAClE,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,IAAI,aAAwE,CAAC;AACpF,0FAA0F;AAC1F,IAAI,OAAmC,CAAC;AAExC;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAgB;IACjD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO;IACT,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC;IACjB,MAAM,IAAI,GAAG,CAAC,IAA0B,EAAQ,EAAE;QAChD,aAAa,GAAG,IAAI,CAAC;QACrB,MAAM,KAAK,GAAG,OAAO,IAAI,EAAE,CAAC;QAC5B,OAAO,GAAG,SAAS,CAAC;QACpB,2FAA2F;QAC3F,6CAA6C;QAC7C,KAAK,MAAM,IAAI,IAAI,KAAK;YAAE,cAAc,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC,CAAC;IACF,IAAI,CACF,MAAM,CAAC,uBAAuB,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,KAAc,EAAE,EAAE;QAC5D,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,CAAC,CAAC,CACH,CAAC;AACJ,CAAC","sourcesContent":["// The client's half of seeds and hydration loading (view/07-hydration.md \"Loading\"), core's\n// `#hydration-loader`: reads a server-rendered host's seed on connect and loads the hydration\n// walk (hydration-client.ts) with import() when the first host that needs it connects.\n// Client-only builds (`gyralVitePreset({ clientOnly: true })`, gyral-c5d.11) resolve\n// `#hydration-loader` to hydration-off.ts instead: no import(), so no hydration chunk.\nimport { SEED_ATTRIBUTE, type Seed } from './hydration.js';\nimport { hold } from './scheduler.js';\nimport { message } from './view/index.js';\n\n/** Client side: reads and removes the seed, if this element was server-rendered by Gyral. */\nexport function takeSeed(host: Element): Seed | undefined {\n  const raw = host.getAttribute(SEED_ATTRIBUTE);\n  if (raw === null) return undefined;\n  host.removeAttribute(SEED_ATTRIBUTE);\n  try {\n    const parsed = JSON.parse(raw) as Partial<Seed> | null;\n    if (parsed === null || typeof parsed !== 'object') return undefined;\n    const props = parsed.props ?? {};\n    return 'state' in parsed ? { state: parsed.state, props } : { props };\n  } catch (error) {\n    console.error(message(60, host.localName, SEED_ATTRIBUTE), error);\n    return undefined;\n  }\n}\n\n/**\n * The walk and islands (hydration-client.ts) once loaded; `null` if loading failed (a stale\n * deployment: server-rendered hosts then render fresh); undefined until then.\n */\nexport let hydrationCode: typeof import('./hydration-client.js') | null | undefined;\n/** Hosts waiting for the code, in connection order; undefined when no load is pending. */\nlet waiting: (() => void)[] | undefined;\n\n/**\n * Loads the hydration code (once) and runs `next` when it has loaded or failed, in call\n * order. settled() waits meanwhile (view/07-hydration.md \"Loading\").\n */\nexport function whenHydrationLoads(next: () => void): void {\n  if (waiting !== undefined) {\n    waiting.push(next);\n    return;\n  }\n  waiting = [next];\n  const done = (code: typeof hydrationCode): void => {\n    hydrationCode = code;\n    const hosts = waiting ?? [];\n    waiting = undefined;\n    // Each in its own microtask, in order: one host throwing doesn't stop the others. They all\n    // run before `hold` counts the load as done.\n    for (const host of hosts) queueMicrotask(host);\n  };\n  hold(\n    import('./hydration-client.js').then(done, (error: unknown) => {\n      console.error(message(61), error);\n      done(null);\n    }),\n  );\n}\n"]}

package/dist/hydration-off.d.ts

@@ -0,0 +1,8 @@
+import type * as Loader from './hydration-loader.js';
+import { type Seed } from './hydration.js';
+/** A seed means server-rendered markup: drop it, so the host renders fresh. */
+export declare const takeSeed: (host: Element) => Seed | undefined;
+/** Never loads: server-rendered hosts render fresh, as after a failed load. */
+export declare const hydrationCode: typeof Loader.hydrationCode;
+/** Not reached (`hydrationCode` is never undefined); runs `next` at once. */
+export declare const whenHydrationLoads: (next: () => void) => void;

package/dist/hydration-off.js

@@ -0,0 +1,25 @@
+import { SEED_ATTRIBUTE } from './hydration.js';
+import { DEV } from './view/index.js';
+let warned = false;
+/** A seed means server-rendered markup: drop it, so the host renders fresh. */
+export const takeSeed = ((host) => {
+    if (!host.hasAttribute(SEED_ATTRIBUTE))
+        return undefined;
+    host.removeAttribute(SEED_ATTRIBUTE);
+    if (DEV && !warned) {
+        warned = true;
+        console.warn(`gyral: <${host.localName}> was server-rendered (it has a hydration seed), but this app ` +
+            `is built client-only (gyralVitePreset({ clientOnly: true })), which leaves the ` +
+            `hydration code out: it renders fresh, replacing the server's markup, and so does every ` +
+            `server-rendered host. Drop clientOnly for apps that render on the server ` +
+            `(view/07-hydration.md "Client-only builds").`);
+    }
+    return { props: {} };
+});
+/** Never loads: server-rendered hosts render fresh, as after a failed load. */
+export const hydrationCode = null;
+/** Not reached (`hydrationCode` is never undefined); runs `next` at once. */
+export const whenHydrationLoads = ((next) => {
+    next();
+});
+//# sourceMappingURL=hydration-off.js.map

package/dist/hydration-off.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydration-off.js","sourceRoot":"","sources":["../src/hydration-off.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,cAAc,EAAa,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAEtC,IAAI,MAAM,GAAG,KAAK,CAAC;AAEnB,+EAA+E;AAC/E,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,IAAa,EAAoB,EAAE;IAC3D,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,cAAc,CAAC;QAAE,OAAO,SAAS,CAAC;IACzD,IAAI,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;IACrC,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,GAAG,IAAI,CAAC;QACd,OAAO,CAAC,IAAI,CACV,WAAW,IAAI,CAAC,SAAS,gEAAgE;YACvF,iFAAiF;YACjF,yFAAyF;YACzF,2EAA2E;YAC3E,8CAA8C,CACjD,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AACvB,CAAC,CAAkC,CAAC;AAEpC,+EAA+E;AAC/E,MAAM,CAAC,MAAM,aAAa,GAAgC,IAAI,CAAC;AAE/D,6EAA6E;AAC7E,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,IAAgB,EAAQ,EAAE;IAC5D,IAAI,EAAE,CAAC;AACT,CAAC,CAA4C,CAAC","sourcesContent":["// `#hydration-loader` in client-only builds (`gyralVitePreset({ clientOnly: true })`,\n// gyral-c5d.11, view/07-hydration.md \"Client-only builds\"): the same exports as\n// hydration-loader.ts, without the hydration walk or its import(), so the bundle has no\n// hydration chunk (and, without other import()s, no preload helper). A server-rendered host\n// met anyway renders fresh: its seed is dropped (init runs from its attributes), `hydrationCode`\n// is `null` as after a failed load, so element.ts clears the root, and islands start at once.\n// Development warns once; production renders fresh silently.\nimport type * as Loader from './hydration-loader.js';\nimport { SEED_ATTRIBUTE, type Seed } from './hydration.js';\nimport { DEV } from './view/index.js';\n\nlet warned = false;\n\n/** A seed means server-rendered markup: drop it, so the host renders fresh. */\nexport const takeSeed = ((host: Element): Seed | undefined => {\n  if (!host.hasAttribute(SEED_ATTRIBUTE)) return undefined;\n  host.removeAttribute(SEED_ATTRIBUTE);\n  if (DEV && !warned) {\n    warned = true;\n    console.warn(\n      `gyral: <${host.localName}> was server-rendered (it has a hydration seed), but this app ` +\n        `is built client-only (gyralVitePreset({ clientOnly: true })), which leaves the ` +\n        `hydration code out: it renders fresh, replacing the server's markup, and so does every ` +\n        `server-rendered host. Drop clientOnly for apps that render on the server ` +\n        `(view/07-hydration.md \"Client-only builds\").`,\n    );\n  }\n  return { props: {} };\n}) satisfies typeof Loader.takeSeed;\n\n/** Never loads: server-rendered hosts render fresh, as after a failed load. */\nexport const hydrationCode: typeof Loader.hydrationCode = null;\n\n/** Not reached (`hydrationCode` is never undefined); runs `next` at once. */\nexport const whenHydrationLoads = ((next: () => void): void => {\n  next();\n}) satisfies typeof Loader.whenHydrationLoads;\n"]}

package/dist/hydration.d.ts

@@ -1,4 +1,3 @@
-import type { PropertyDeclaration } from 'lit';
 /** Host attribute holding the JSON seed. Removed once the client has read it. */
 export declare const SEED_ATTRIBUTE = "data-gyral-seed";
 export interface Seed {
@@ -12,25 +11,8 @@ export interface Seed {
 }
 /** JSON equality: seeds are JSON, so two values that serialize alike hydrate alike. */
 export declare const sameJson: (a: unknown, b: unknown) => boolean;
-type Declarations = Readonly<Record<string, PropertyDeclaration>>;
 /**
- * Server side: records the element's state and its props that are not already present as
- * attributes (property bindings such as `.items=${data}` are not in the HTML otherwise).
- * The SSR renderer escapes attribute values, so the JSON is HTML-safe.
+ * Server side: the seed for a component whose props `carried` travel in no attribute
+ * (property holes) and whose state is `state`; `initial` is `init(props)`'s state.
  */
-export declare function writeSeed(host: Element, state: unknown, props: Readonly<Record<string, unknown>>, declarations: Declarations, initialState?: {
-    readonly value: unknown;
-}): void;
-/**
- * Client side, right after hydration (gyral-4k7.12, ADR 0012): Lit SSR writes nothing for
- * an empty primitive (`''`, `null`, `undefined`), so `<!--lit-part--><!--/lit-part-->`
- * has no Text node between the markers. Hydration still records the primitive as the
- * part's committed value, and the next text commit writes `.data` into the
- * `<!--/lit-part-->` comment instead. Restore the empty Text node a client render would
- * have created. Harmless for `nothing` and empty iterables, which clear or insert before
- * the end marker. Shadow roots below `root` are handled by their own hosts.
- */
-export declare function fillEmptyTextParts(root: Node): void;
-/** Client side: reads and removes the seed, if this element was server-rendered by Gyral. */
-export declare function takeSeed(host: Element): Seed | undefined;
-export {};
+export declare function makeSeed(tag: string, state: unknown, initial: unknown, carried: Readonly<Record<string, unknown>>): Seed;

package/dist/hydration.js

@@ -1,72 +1,23 @@
+// Server-render seeds (docs/design-docs/0012-ssr.md, view/06-server.md "Components"). The
+// server writes each component's state, plus the props an attribute can't carry, into one
+// attribute; the client reads it on connect, before its first render, so both sides start from
+// the same state. The client reads seeds in hydration-loader.ts (core's `#hydration-loader`:
+// hydration-off.ts in client-only builds); the walk that then hydrates the server's DOM is
+// hydration-client.ts, which the loader imports lazily (view/07-hydration.md "Loading").
 import { warnJsonHazard } from './json-safety.js';
+import { DEV } from './view/index.js';
 /** Host attribute holding the JSON seed. Removed once the client has read it. */
 export const SEED_ATTRIBUTE = 'data-gyral-seed';
 /** JSON equality: seeds are JSON, so two values that serialize alike hydrate alike. */
 export const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
-function attributeName(name, decl) {
-    if (decl.attribute === false)
-        return undefined;
-    return typeof decl.attribute === 'string' ? decl.attribute : name.toLowerCase();
-}
 /**
- * Server side: records the element's state and its props that are not already present as
- * attributes (property bindings such as `.items=${data}` are not in the HTML otherwise).
- * The SSR renderer escapes attribute values, so the JSON is HTML-safe.
+ * Server side: the seed for a component whose props `carried` travel in no attribute
+ * (property holes) and whose state is `state`; `initial` is `init(props)`'s state.
  */
-export function writeSeed(host, state, props, declarations, initialState) {
-    const carried = {};
-    for (const [name, value] of Object.entries(props)) {
-        const decl = declarations[name] ?? {};
-        const attr = attributeName(name, decl);
-        if (value !== undefined && (attr === undefined || !host.hasAttribute(attr))) {
-            carried[name] = value;
-        }
-    }
-    const derivable = initialState !== undefined && sameJson(state, initialState.value);
-    const seed = derivable ? { props: carried } : { state, props: carried };
-    warnJsonHazard(`<${host.localName}>`, seed, 'seed');
-    host.setAttribute(SEED_ATTRIBUTE, JSON.stringify(seed));
-}
-/**
- * Client side, right after hydration (gyral-4k7.12, ADR 0012): Lit SSR writes nothing for
- * an empty primitive (`''`, `null`, `undefined`), so `<!--lit-part--><!--/lit-part-->`
- * has no Text node between the markers. Hydration still records the primitive as the
- * part's committed value, and the next text commit writes `.data` into the
- * `<!--/lit-part-->` comment instead. Restore the empty Text node a client render would
- * have created. Harmless for `nothing` and empty iterables, which clear or insert before
- * the end marker. Shadow roots below `root` are handled by their own hosts.
- */
-export function fillEmptyTextParts(root) {
-    const doc = root.ownerDocument ?? root;
-    const walker = doc.createTreeWalker(root, NodeFilter.SHOW_COMMENT);
-    const empty = [];
-    for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
-        const next = node.nextSibling;
-        if (node.data === 'lit-part' &&
-            next instanceof Comment &&
-            next.data === '/lit-part') {
-            empty.push(node);
-        }
-    }
-    for (const start of empty)
-        start.after(doc.createTextNode(''));
-}
-/** Client side: reads and removes the seed, if this element was server-rendered by Gyral. */
-export function takeSeed(host) {
-    const raw = host.getAttribute(SEED_ATTRIBUTE);
-    if (raw === null)
-        return undefined;
-    host.removeAttribute(SEED_ATTRIBUTE);
-    try {
-        const parsed = JSON.parse(raw);
-        if (parsed === null || typeof parsed !== 'object')
-            return undefined;
-        const props = parsed.props ?? {};
-        return 'state' in parsed ? { state: parsed.state, props } : { props };
-    }
-    catch (error) {
-        console.error(`<${host.localName}> has an unreadable ${SEED_ATTRIBUTE}`, error);
-        return undefined;
-    }
+export function makeSeed(tag, state, initial, carried) {
+    const seed = sameJson(state, initial) ? { props: carried } : { state, props: carried };
+    if (DEV)
+        warnJsonHazard(`<${tag}>`, seed, 'seed'); // view/06-server.md "Seed": development
+    return seed;
 }
 //# sourceMappingURL=hydration.js.map