@craft-ts/core 0.7.0-beta.13

package/src/lib/craft-settled.d.ts

@@ -0,0 +1,171 @@
+import { type Signal } from './host/craft-compat';
+import { type CraftGenExceptionMarker } from './craft-gen';
+import type { AnyCraftException } from './craft-exception';
+import type { CraftResourceStatus } from './util/craft-resource-status';
+import type { ReactiveReadRequest, YieldableReactiveValue } from './reactive-read';
+declare const CRAFT_NOT_SETTLED: unique symbol;
+/**
+ * Thrown by a {@link CraftSettledSignal} read while its source has not settled
+ * yet (`status` still `'idle'` or `'loading'`).
+ *
+ * It is the pending twin of {@link CraftGenShortCircuit}: both are native
+ * `throw`s raised during a render pass and caught by the nearest boundary — a
+ * `catchBlock` for the exception, a `pendingBlock` for this one. The dependency
+ * on the source's `status` signal is established *before* the throw, so the
+ * reading computation re-runs on its own once the source settles.
+ */
+export declare class CraftNotSettled extends Error {
+    readonly [CRAFT_NOT_SETTLED] = true;
+    /** Name of the async source that is not settled yet (`query` name, …). */
+    readonly source: string;
+    constructor(source: string);
+}
+export declare function isCraftNotSettled(value: unknown): value is CraftNotSettled;
+declare const CRAFT_SETTLED_BRAND: unique symbol;
+/**
+ * Type-only brand carried by a {@link CraftSettledSignal}. It records **which**
+ * async source the reader depends on and **which** exception codes that source
+ * may raise, so both requirements can be enforced by the template type-checker:
+ *
+ * - `Source` must be covered by a `pendingBlock` boundary;
+ * - `Codes` must be covered by a `catchBlock` boundary.
+ *
+ * The brand survives passing the signal by reference (`span(users.settledValue)`)
+ * and travels through `craftComputed` via the marker yielded by {@link settled}.
+ * It is lost inside a lambda (`() => users.settledValue().name`) — that case is
+ * a lint concern, not a type one.
+ */
+export interface CraftSettledBrand<Source extends string = string, Exceptions = never> {
+    readonly [CRAFT_SETTLED_BRAND]: {
+        readonly source: Source;
+        readonly exceptions: Exceptions;
+    };
+}
+/**
+ * A `Signal<Value>` that never returns `undefined` and never returns a value
+ * while its source carries an exception — it throws instead (see
+ * {@link CraftNotSettled}). Its brand makes both obligations visible to the
+ * template type-checker.
+ */
+export type CraftSettledSignal<Value, Source extends string = string, Exceptions = never> = Signal<Value> & CraftSettledBrand<Source, Exceptions>;
+/** Type-only yields carried by a direct settled reader in a generator. */
+export type CraftSettledReadMarkers<Source extends string, Exceptions> = CraftPendingMarker<Source> | CraftGenExceptionMarker<Exceptions>;
+/** A settled reader that can be consumed directly with `yield* reader()`. */
+export type CraftSettledYieldableValue<Value, Source extends string = string, Exceptions = never> = YieldableReactiveValue<Value, 'settledState', CraftSettledReadMarkers<Source, Exceptions>> & CraftSettledBrand<Source, Exceptions>;
+/** The async source names a value depends on (`never` when it depends on none). */
+export type CraftSettledSourcesOf<Value> = Value extends CraftSettledBrand<infer Source, any> ? string extends Source ? never : Source : never;
+/** The `craftException`s a settled read may surface. */
+export type CraftSettledExceptionsOf<Value> = Value extends CraftSettledBrand<any, infer Exceptions> ? Exceptions : never;
+/** The exception codes a settled read may surface. */
+export type CraftSettledCodesOf<Value> = Extract<CraftSettledExceptionsOf<Value>, {
+    readonly _tag: string;
+}>['_tag'];
+/**
+ * Type-level marker surfaced by a {@link settled} call's `Yielded`, carrying the
+ * name of the async source the enclosing computation now depends on.
+ *
+ * Like {@link CraftGenExceptionMarker} it is **never** yielded at runtime, and is
+ * intentionally not a `ServiceYieldRequest` so dependency-map extraction ignores
+ * it.
+ */
+export interface CraftPendingMarker<Source extends string> {
+    readonly __craftPendingSource__: Source;
+}
+/** Extracts the union of async source names advertised by the markers in `Yielded`. */
+export type ExtractCraftPendingSources<Yielded> = [
+    Extract<Yielded, CraftPendingMarker<any>>
+] extends [never] ? never : Extract<Yielded, CraftPendingMarker<any>> extends CraftPendingMarker<infer Source> ? Source : never;
+/**
+ * What a settled read reports about its source to whoever is listening — today
+ * a `pendingBlock` boundary, which needs a handle on the source's liveness to
+ * render a reload indicator.
+ *
+ * A suspension is announced by a `throw`, but a **reload** is not: the stale
+ * value is returned and nothing is thrown. Without this channel a boundary
+ * would never learn that a source it covers is refetching.
+ */
+export interface CraftSettledReadNotice {
+    readonly source: string;
+    readonly status: Signal<CraftResourceStatus | string>;
+    readonly value: Signal<unknown>;
+}
+export type CraftSettledReadObserver = (notice: CraftSettledReadNotice) => void;
+/**
+ * Runs `work` with `observer` notified of every settled read it performs. The
+ * observer is registered for the synchronous extent of the call — settled reads
+ * are computations, so they evaluate inside the reader's own effect.
+ */
+export declare function ɵwithSettledReadObserver<T>(observer: CraftSettledReadObserver | undefined, work: () => T): T;
+/** The minimal shape {@link craftSettledValue} needs to build a settled read. */
+export type SettleableResource = {
+    status: Signal<CraftResourceStatus | string>;
+    value: Signal<unknown>;
+    error?: Signal<Error | undefined>;
+    hasException: Signal<boolean>;
+    exceptions: Signal<{
+        list: readonly AnyCraftException[];
+    }>;
+};
+/**
+ * Builds the `settledValue` signal of a craft primitive. Reading it:
+ *
+ * - throws {@link CraftGenShortCircuit} when the source carries a business
+ *   exception — routed to the nearest `catchBlock`;
+ * - throws {@link CraftNotSettled} while the source has no value to show yet —
+ *   routed to the nearest `pendingBlock`;
+ * - otherwise returns the resolved value, never `undefined`.
+ *
+ * A reload that preserves its previous value does **not** suspend: the stale
+ * value is returned while the new one is in flight (stale-while-revalidate), so
+ * a refetch never blanks a screen that already has data. Only a source with
+ * nothing to show suspends.
+ *
+ * A residual technical failure (status `'exception'` with no business exception)
+ * is rethrown through the internal Angular `error` channel, mirroring
+ * `craftUntilSettled`.
+ */
+export declare function craftSettledValue<Value>(source: string, resource: SettleableResource): CraftSettledSignal<Value>;
+type SettledReaderOf<Ref> = Ref extends {
+    settledValue: YieldableReactiveValue<infer Value, any, any> & CraftSettledBrand<infer Source, infer Exceptions>;
+} ? YieldableReactiveValue<Value> & CraftSettledBrand<Source, Exceptions> : never;
+/**
+ * Reads the settled value of a craft primitive from inside a generator-based
+ * computation, and records the dependency in its type:
+ *
+ * ```ts
+ * readonly activeUserName = craftComputed('activeUserName', function* () {
+ *   const users = yield* settled(this.users);
+ *   // `users` is `User[]` here — never undefined, never in exception
+ *   return users.filter((user) => user.active).length;
+ * });
+ * ```
+ *
+ * The primitive's `settledValue` reader is executed immediately by the Craft
+ * generator runtime. The additional yielded markers are type-only and make the
+ * enclosing `craftComputed`:
+ *
+ * - depend on the source's pending state — a `pendingBlock` becomes mandatory in
+ *   any template rendering it;
+ * - carry the source's exceptions — a `catchBlock` becomes mandatory too.
+ */
+export declare function settled<const Ref extends {
+    readonly settledValue: YieldableReactiveValue<any, any, any> & CraftSettledBrand<any, any>;
+}>(resource: Ref): Generator<CraftPendingMarker<SettledReaderOf<Ref> extends CraftSettledBrand<infer Source, any> ? Source : never> | CraftGenExceptionMarker<CraftSettledExceptionsOf<SettledReaderOf<Ref>>> | ReactiveReadRequest, SettledReaderOf<Ref> extends YieldableReactiveValue<infer Value> ? Value : never, unknown>;
+/**
+ * Installs the lazily-created `settledValue` read on a resource-like primitive
+ * ref (`query`, `mutation`, `asyncProcess`).
+ *
+ * It is a getter — the computation is only built on first read — and it is
+ * **enumerable**: a template context is rebuilt by copying the ref's own
+ * enumerable members, so a hidden property would not survive the trip into the
+ * template.
+ */
+export declare function attachCraftSettledValue(name: string, ref: object): void;
+/** Creates an insertion-facing generator reader over a settled raw signal. */
+export declare function createYieldableSettledValue<Value, Source extends string, Exceptions>(source: Signal<Value>, identity: {
+    readonly primitive?: string;
+    readonly insertion?: string;
+    readonly path?: string;
+}): CraftSettledYieldableValue<Value, Source, Exceptions>;
+export {};
+//# sourceMappingURL=craft-settled.d.ts.map

package/src/lib/craft-settled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft-settled.d.ts","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-settled.ts"],"names":[],"mappings":"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"}

package/src/lib/craft-settled.js

@@ -0,0 +1,130 @@
+import { computed } from './host/craft-compat';
+import { CraftGenShortCircuit, } from './craft-gen';
+import { createYieldableReactiveValue } from './reactive-read';
+const CRAFT_NOT_SETTLED = Symbol('craft-not-settled');
+/**
+ * Thrown by a {@link CraftSettledSignal} read while its source has not settled
+ * yet (`status` still `'idle'` or `'loading'`).
+ *
+ * It is the pending twin of {@link CraftGenShortCircuit}: both are native
+ * `throw`s raised during a render pass and caught by the nearest boundary — a
+ * `catchBlock` for the exception, a `pendingBlock` for this one. The dependency
+ * on the source's `status` signal is established *before* the throw, so the
+ * reading computation re-runs on its own once the source settles.
+ */
+export class CraftNotSettled extends Error {
+    [CRAFT_NOT_SETTLED] = true;
+    /** Name of the async source that is not settled yet (`query` name, …). */
+    source;
+    constructor(source) {
+        super(`Craft async source "${source}" is not settled yet. Wrap the reading template in a pendingBlock(...).`);
+        this.name = 'CraftNotSettled';
+        this.source = source;
+    }
+}
+export function isCraftNotSettled(value) {
+    return (typeof value === 'object' && value !== null && CRAFT_NOT_SETTLED in value);
+}
+let activeSettledReadObserver;
+/**
+ * Runs `work` with `observer` notified of every settled read it performs. The
+ * observer is registered for the synchronous extent of the call — settled reads
+ * are computations, so they evaluate inside the reader's own effect.
+ */
+export function ɵwithSettledReadObserver(observer, work) {
+    const previous = activeSettledReadObserver;
+    activeSettledReadObserver = observer ?? previous;
+    try {
+        return work();
+    }
+    finally {
+        activeSettledReadObserver = previous;
+    }
+}
+/**
+ * Builds the `settledValue` signal of a craft primitive. Reading it:
+ *
+ * - throws {@link CraftGenShortCircuit} when the source carries a business
+ *   exception — routed to the nearest `catchBlock`;
+ * - throws {@link CraftNotSettled} while the source has no value to show yet —
+ *   routed to the nearest `pendingBlock`;
+ * - otherwise returns the resolved value, never `undefined`.
+ *
+ * A reload that preserves its previous value does **not** suspend: the stale
+ * value is returned while the new one is in flight (stale-while-revalidate), so
+ * a refetch never blanks a screen that already has data. Only a source with
+ * nothing to show suspends.
+ *
+ * A residual technical failure (status `'exception'` with no business exception)
+ * is rethrown through the internal Angular `error` channel, mirroring
+ * `craftUntilSettled`.
+ */
+export function craftSettledValue(source, resource) {
+    return computed(() => {
+        const status = resource.status();
+        activeSettledReadObserver?.({
+            source,
+            status: resource.status,
+            value: resource.value,
+        });
+        if (resource.hasException()) {
+            throw new CraftGenShortCircuit(resource.exceptions().list[0]);
+        }
+        if (status === 'exception') {
+            throw resource.error?.();
+        }
+        const value = resource.value();
+        if (value === undefined) {
+            throw new CraftNotSettled(source);
+        }
+        return value;
+    });
+}
+/**
+ * Reads the settled value of a craft primitive from inside a generator-based
+ * computation, and records the dependency in its type:
+ *
+ * ```ts
+ * readonly activeUserName = craftComputed('activeUserName', function* () {
+ *   const users = yield* settled(this.users);
+ *   // `users` is `User[]` here — never undefined, never in exception
+ *   return users.filter((user) => user.active).length;
+ * });
+ * ```
+ *
+ * The primitive's `settledValue` reader is executed immediately by the Craft
+ * generator runtime. The additional yielded markers are type-only and make the
+ * enclosing `craftComputed`:
+ *
+ * - depend on the source's pending state — a `pendingBlock` becomes mandatory in
+ *   any template rendering it;
+ * - carry the source's exceptions — a `catchBlock` becomes mandatory too.
+ */
+export function* settled(resource) {
+    const read = resource.settledValue;
+    return yield* read();
+}
+/**
+ * Installs the lazily-created `settledValue` read on a resource-like primitive
+ * ref (`query`, `mutation`, `asyncProcess`).
+ *
+ * It is a getter — the computation is only built on first read — and it is
+ * **enumerable**: a template context is rebuilt by copying the ref's own
+ * enumerable members, so a hidden property would not survive the trip into the
+ * template.
+ */
+export function attachCraftSettledValue(name, ref) {
+    if ('settledValue' in ref)
+        return;
+    let cached;
+    Object.defineProperty(ref, 'settledValue', {
+        get: () => (cached ??= craftSettledValue(name, ref)),
+        enumerable: true,
+        configurable: true,
+    });
+}
+/** Creates an insertion-facing generator reader over a settled raw signal. */
+export function createYieldableSettledValue(source, identity) {
+    return createYieldableReactiveValue(source, 'settledState', identity);
+}
+//# sourceMappingURL=craft-settled.js.map

package/src/lib/craft-settled.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft-settled.js","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-settled.ts"],"names":[],"mappings":"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","sourcesContent":["import { computed, type Signal } from './host/craft-compat';\nimport {\n  CraftGenShortCircuit,\n  type CraftGenExceptionMarker,\n} from './craft-gen';\nimport type { AnyCraftException } from './craft-exception';\nimport type { CraftResourceStatus } from './util/craft-resource-status';\nimport type {\n  ReactiveReadRequest,\n  YieldableReactiveValue,\n} from './reactive-read';\nimport { createYieldableReactiveValue } from './reactive-read';\n\nconst CRAFT_NOT_SETTLED = Symbol('craft-not-settled');\n\n/**\n * Thrown by a {@link CraftSettledSignal} read while its source has not settled\n * yet (`status` still `'idle'` or `'loading'`).\n *\n * It is the pending twin of {@link CraftGenShortCircuit}: both are native\n * `throw`s raised during a render pass and caught by the nearest boundary — a\n * `catchBlock` for the exception, a `pendingBlock` for this one. The dependency\n * on the source's `status` signal is established *before* the throw, so the\n * reading computation re-runs on its own once the source settles.\n */\nexport class CraftNotSettled extends Error {\n  readonly [CRAFT_NOT_SETTLED] = true;\n  /** Name of the async source that is not settled yet (`query` name, …). */\n  readonly source: string;\n\n  constructor(source: string) {\n    super(\n      `Craft async source \"${source}\" is not settled yet. Wrap the reading template in a pendingBlock(...).`,\n    );\n    this.name = 'CraftNotSettled';\n    this.source = source;\n  }\n}\n\nexport function isCraftNotSettled(value: unknown): value is CraftNotSettled {\n  return (\n    typeof value === 'object' && value !== null && CRAFT_NOT_SETTLED in value\n  );\n}\n\ndeclare const CRAFT_SETTLED_BRAND: unique symbol;\n\n/**\n * Type-only brand carried by a {@link CraftSettledSignal}. It records **which**\n * async source the reader depends on and **which** exception codes that source\n * may raise, so both requirements can be enforced by the template type-checker:\n *\n * - `Source` must be covered by a `pendingBlock` boundary;\n * - `Codes` must be covered by a `catchBlock` boundary.\n *\n * The brand survives passing the signal by reference (`span(users.settledValue)`)\n * and travels through `craftComputed` via the marker yielded by {@link settled}.\n * It is lost inside a lambda (`() => users.settledValue().name`) — that case is\n * a lint concern, not a type one.\n */\nexport interface CraftSettledBrand<\n  Source extends string = string,\n  Exceptions = never,\n> {\n  // Required (never present at runtime) so that extraction is exact: an\n  // unbranded signal simply does not match, instead of matching with the\n  // parameters falling back to their constraint.\n  readonly [CRAFT_SETTLED_BRAND]: {\n    readonly source: Source;\n    readonly exceptions: Exceptions;\n  };\n}\n\n/**\n * A `Signal<Value>` that never returns `undefined` and never returns a value\n * while its source carries an exception — it throws instead (see\n * {@link CraftNotSettled}). Its brand makes both obligations visible to the\n * template type-checker.\n */\nexport type CraftSettledSignal<\n  Value,\n  Source extends string = string,\n  Exceptions = never,\n> = Signal<Value> & CraftSettledBrand<Source, Exceptions>;\n\n/** Type-only yields carried by a direct settled reader in a generator. */\nexport type CraftSettledReadMarkers<Source extends string, Exceptions> =\n  | CraftPendingMarker<Source>\n  | CraftGenExceptionMarker<Exceptions>;\n\n/** A settled reader that can be consumed directly with `yield* reader()`. */\nexport type CraftSettledYieldableValue<\n  Value,\n  Source extends string = string,\n  Exceptions = never,\n> = YieldableReactiveValue<\n  Value,\n  'settledState',\n  CraftSettledReadMarkers<Source, Exceptions>\n> &\n  CraftSettledBrand<Source, Exceptions>;\n\n/** The async source names a value depends on (`never` when it depends on none). */\nexport type CraftSettledSourcesOf<Value> =\n  Value extends CraftSettledBrand<infer Source, any>\n    ? string extends Source\n      ? never\n      : Source\n    : never;\n\n/** The `craftException`s a settled read may surface. */\nexport type CraftSettledExceptionsOf<Value> =\n  Value extends CraftSettledBrand<any, infer Exceptions> ? Exceptions : never;\n\n/** The exception codes a settled read may surface. */\nexport type CraftSettledCodesOf<Value> = Extract<\n  CraftSettledExceptionsOf<Value>,\n  { readonly _tag: string }\n>['_tag'];\n\n/**\n * Type-level marker surfaced by a {@link settled} call's `Yielded`, carrying the\n * name of the async source the enclosing computation now depends on.\n *\n * Like {@link CraftGenExceptionMarker} it is **never** yielded at runtime, and is\n * intentionally not a `ServiceYieldRequest` so dependency-map extraction ignores\n * it.\n */\nexport interface CraftPendingMarker<Source extends string> {\n  readonly __craftPendingSource__: Source;\n}\n\n/** Extracts the union of async source names advertised by the markers in `Yielded`. */\nexport type ExtractCraftPendingSources<Yielded> = [\n  Extract<Yielded, CraftPendingMarker<any>>,\n] extends [never]\n  ? never\n  : Extract<Yielded, CraftPendingMarker<any>> extends CraftPendingMarker<\n        infer Source\n      >\n    ? Source\n    : never;\n\n/**\n * What a settled read reports about its source to whoever is listening — today\n * a `pendingBlock` boundary, which needs a handle on the source's liveness to\n * render a reload indicator.\n *\n * A suspension is announced by a `throw`, but a **reload** is not: the stale\n * value is returned and nothing is thrown. Without this channel a boundary\n * would never learn that a source it covers is refetching.\n */\nexport interface CraftSettledReadNotice {\n  readonly source: string;\n  readonly status: Signal<CraftResourceStatus | string>;\n  readonly value: Signal<unknown>;\n}\n\nexport type CraftSettledReadObserver = (notice: CraftSettledReadNotice) => void;\n\nlet activeSettledReadObserver: CraftSettledReadObserver | undefined;\n\n/**\n * Runs `work` with `observer` notified of every settled read it performs. The\n * observer is registered for the synchronous extent of the call — settled reads\n * are computations, so they evaluate inside the reader's own effect.\n */\nexport function ɵwithSettledReadObserver<T>(\n  observer: CraftSettledReadObserver | undefined,\n  work: () => T,\n): T {\n  const previous = activeSettledReadObserver;\n  activeSettledReadObserver = observer ?? previous;\n  try {\n    return work();\n  } finally {\n    activeSettledReadObserver = previous;\n  }\n}\n\n/** The minimal shape {@link craftSettledValue} needs to build a settled read. */\nexport type SettleableResource = {\n  status: Signal<CraftResourceStatus | string>;\n  value: Signal<unknown>;\n  error?: Signal<Error | undefined>;\n  hasException: Signal<boolean>;\n  exceptions: Signal<{ list: readonly AnyCraftException[] }>;\n};\n\n/**\n * Builds the `settledValue` signal of a craft primitive. Reading it:\n *\n * - throws {@link CraftGenShortCircuit} when the source carries a business\n *   exception — routed to the nearest `catchBlock`;\n * - throws {@link CraftNotSettled} while the source has no value to show yet —\n *   routed to the nearest `pendingBlock`;\n * - otherwise returns the resolved value, never `undefined`.\n *\n * A reload that preserves its previous value does **not** suspend: the stale\n * value is returned while the new one is in flight (stale-while-revalidate), so\n * a refetch never blanks a screen that already has data. Only a source with\n * nothing to show suspends.\n *\n * A residual technical failure (status `'exception'` with no business exception)\n * is rethrown through the internal Angular `error` channel, mirroring\n * `craftUntilSettled`.\n */\nexport function craftSettledValue<Value>(\n  source: string,\n  resource: SettleableResource,\n): CraftSettledSignal<Value> {\n  return computed(() => {\n    const status = resource.status();\n\n    activeSettledReadObserver?.({\n      source,\n      status: resource.status,\n      value: resource.value,\n    });\n\n    if (resource.hasException()) {\n      throw new CraftGenShortCircuit(\n        resource.exceptions().list[0] as AnyCraftException,\n      );\n    }\n\n    if (status === 'exception') {\n      throw resource.error?.();\n    }\n\n    const value = resource.value();\n\n    if (value === undefined) {\n      throw new CraftNotSettled(source);\n    }\n\n    return value as Value;\n  }) as CraftSettledSignal<Value>;\n}\n\ntype SettledReaderOf<Ref> = Ref extends {\n  settledValue: YieldableReactiveValue<infer Value, any, any> &\n    CraftSettledBrand<infer Source, infer Exceptions>;\n}\n  ? YieldableReactiveValue<Value> & CraftSettledBrand<Source, Exceptions>\n  : never;\n\n/**\n * Reads the settled value of a craft primitive from inside a generator-based\n * computation, and records the dependency in its type:\n *\n * ```ts\n * readonly activeUserName = craftComputed('activeUserName', function* () {\n *   const users = yield* settled(this.users);\n *   // `users` is `User[]` here — never undefined, never in exception\n *   return users.filter((user) => user.active).length;\n * });\n * ```\n *\n * The primitive's `settledValue` reader is executed immediately by the Craft\n * generator runtime. The additional yielded markers are type-only and make the\n * enclosing `craftComputed`:\n *\n * - depend on the source's pending state — a `pendingBlock` becomes mandatory in\n *   any template rendering it;\n * - carry the source's exceptions — a `catchBlock` becomes mandatory too.\n */\nexport function* settled<\n  const Ref extends {\n    readonly settledValue: YieldableReactiveValue<any, any, any> &\n      CraftSettledBrand<any, any>;\n  },\n>(\n  resource: Ref,\n): Generator<\n  | CraftPendingMarker<\n      SettledReaderOf<Ref> extends CraftSettledBrand<infer Source, any>\n        ? Source\n        : never\n    >\n  | CraftGenExceptionMarker<CraftSettledExceptionsOf<SettledReaderOf<Ref>>>\n  | ReactiveReadRequest,\n  SettledReaderOf<Ref> extends YieldableReactiveValue<infer Value>\n    ? Value\n    : never,\n  unknown\n> {\n  type Value =\n    SettledReaderOf<Ref> extends YieldableReactiveValue<infer T> ? T : never;\n  const read = resource.settledValue as () => Generator<\n    ReactiveReadRequest<Value>,\n    Value,\n    unknown\n  >;\n  return yield* read();\n}\n\n/**\n * Installs the lazily-created `settledValue` read on a resource-like primitive\n * ref (`query`, `mutation`, `asyncProcess`).\n *\n * It is a getter — the computation is only built on first read — and it is\n * **enumerable**: a template context is rebuilt by copying the ref's own\n * enumerable members, so a hidden property would not survive the trip into the\n * template.\n */\nexport function attachCraftSettledValue(name: string, ref: object): void {\n  if ('settledValue' in ref) return;\n\n  let cached: CraftSettledSignal<unknown> | undefined;\n  Object.defineProperty(ref, 'settledValue', {\n    get: () =>\n      (cached ??= craftSettledValue(\n        name,\n        ref as unknown as SettleableResource,\n      )),\n    enumerable: true,\n    configurable: true,\n  });\n}\n\n/** Creates an insertion-facing generator reader over a settled raw signal. */\nexport function createYieldableSettledValue<\n  Value,\n  Source extends string,\n  Exceptions,\n>(\n  source: Signal<Value>,\n  identity: {\n    readonly primitive?: string;\n    readonly insertion?: string;\n    readonly path?: string;\n  },\n): CraftSettledYieldableValue<Value, Source, Exceptions> {\n  return createYieldableReactiveValue(\n    source,\n    'settledState',\n    identity,\n  ) as CraftSettledYieldableValue<Value, Source, Exceptions>;\n}\n"]}

package/src/lib/craft-ssr.d.ts

@@ -0,0 +1,29 @@
+export type SsrMode = 'block' | 'fallback' | 'client';
+export type CraftSsrPolicy = Readonly<{
+    mode: SsrMode;
+    timeoutMs?: number;
+}>;
+/** Nearest route-level default, overridden by a local pendingBlock policy. */
+export declare const CRAFT_SSR_POLICY: import("..").CraftToken<Readonly<{
+    mode: SsrMode;
+    timeoutMs?: number;
+}>>;
+/** Request-scoped bridge used by core async work such as lazy route loading. */
+export type CraftSsrRuntime = Readonly<{
+    track(source: string, work: PromiseLike<unknown>): void;
+}>;
+export declare const CRAFT_SSR_RUNTIME: import("..").CraftToken<Readonly<{
+    track(source: string, work: PromiseLike<unknown>): void;
+}>>;
+export declare class CraftUnhandledSsrResolutionError extends Error {
+    readonly source: string;
+    readonly route?: string;
+    readonly reason: 'no pendingBlock or route SSR policy';
+    constructor(source: string, route?: string);
+}
+export declare class CraftSsrTimeoutError extends Error {
+    readonly timeoutMs: number;
+    readonly sources: readonly string[];
+    constructor(timeoutMs: number, sources: readonly string[]);
+}
+//# sourceMappingURL=craft-ssr.d.ts.map

package/src/lib/craft-ssr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft-ssr.d.ts","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-ssr.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEtD,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAEH,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB;UALrB,OAAO;gBACD,MAAM;GAIwD,CAAC;AAE7E,gFAAgF;AAChF,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CACzD,CAAC,CAAC;AAEH,eAAO,MAAM,iBAAiB;kBAHd,MAAM,QAAQ,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI;GAGsB,CAAC;AAEhF,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,qCAAqC,CAAC;gBAE3C,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAS3C;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;gBAExB,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE;CAQ1D"}

package/src/lib/craft-ssr.js

@@ -0,0 +1,27 @@
+import { craftToken } from './host/craft-injector';
+/** Nearest route-level default, overridden by a local pendingBlock policy. */
+export const CRAFT_SSR_POLICY = craftToken('CraftSsrPolicy');
+export const CRAFT_SSR_RUNTIME = craftToken('CraftSsrRuntime');
+export class CraftUnhandledSsrResolutionError extends Error {
+    source;
+    route;
+    reason;
+    constructor(source, route) {
+        super(`Craft async source "${source}" suspended during SSR without a pendingBlock or route SSR policy${route ? ` (route: ${route})` : ''}.`);
+        this.name = 'CraftUnhandledSsrResolutionError';
+        this.source = source;
+        this.route = route;
+        this.reason = 'no pendingBlock or route SSR policy';
+    }
+}
+export class CraftSsrTimeoutError extends Error {
+    timeoutMs;
+    sources;
+    constructor(timeoutMs, sources) {
+        super(`Craft SSR timed out after ${timeoutMs}ms while waiting for: ${sources.join(', ')}.`);
+        this.name = 'CraftSsrTimeoutError';
+        this.timeoutMs = timeoutMs;
+        this.sources = sources;
+    }
+}
+//# sourceMappingURL=craft-ssr.js.map

package/src/lib/craft-ssr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft-ssr.js","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-ssr.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AASnD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,CAAiB,gBAAgB,CAAC,CAAC;AAO7E,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAkB,iBAAiB,CAAC,CAAC;AAEhF,MAAM,OAAO,gCAAiC,SAAQ,KAAK;IAChD,MAAM,CAAS;IACf,KAAK,CAAU;IACf,MAAM,CAAwC;IAEvD,YAAY,MAAc,EAAE,KAAc;QACxC,KAAK,CACH,uBAAuB,MAAM,oEAAoE,KAAK,CAAC,CAAC,CAAC,YAAY,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CACtI,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kCAAkC,CAAC;QAC/C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,qCAAqC,CAAC;IACtD,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,SAAS,CAAS;IAClB,OAAO,CAAoB;IAEpC,YAAY,SAAiB,EAAE,OAA0B;QACvD,KAAK,CACH,6BAA6B,SAAS,yBAAyB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACrF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF","sourcesContent":["import { craftToken } from './host/craft-injector';\n\nexport type SsrMode = 'block' | 'fallback' | 'client';\n\nexport type CraftSsrPolicy = Readonly<{\n  mode: SsrMode;\n  timeoutMs?: number;\n}>;\n\n/** Nearest route-level default, overridden by a local pendingBlock policy. */\nexport const CRAFT_SSR_POLICY = craftToken<CraftSsrPolicy>('CraftSsrPolicy');\n\n/** Request-scoped bridge used by core async work such as lazy route loading. */\nexport type CraftSsrRuntime = Readonly<{\n  track(source: string, work: PromiseLike<unknown>): void;\n}>;\n\nexport const CRAFT_SSR_RUNTIME = craftToken<CraftSsrRuntime>('CraftSsrRuntime');\n\nexport class CraftUnhandledSsrResolutionError extends Error {\n  readonly source: string;\n  readonly route?: string;\n  readonly reason: 'no pendingBlock or route SSR policy';\n\n  constructor(source: string, route?: string) {\n    super(\n      `Craft async source \"${source}\" suspended during SSR without a pendingBlock or route SSR policy${route ? ` (route: ${route})` : ''}.`,\n    );\n    this.name = 'CraftUnhandledSsrResolutionError';\n    this.source = source;\n    this.route = route;\n    this.reason = 'no pendingBlock or route SSR policy';\n  }\n}\n\nexport class CraftSsrTimeoutError extends Error {\n  readonly timeoutMs: number;\n  readonly sources: readonly string[];\n\n  constructor(timeoutMs: number, sources: readonly string[]) {\n    super(\n      `Craft SSR timed out after ${timeoutMs}ms while waiting for: ${sources.join(', ')}.`,\n    );\n    this.name = 'CraftSsrTimeoutError';\n    this.timeoutMs = timeoutMs;\n    this.sources = sources;\n  }\n}\n"]}

package/src/lib/craft-state-machine-runtime.d.ts

@@ -0,0 +1,88 @@
+import { Injector, type Signal } from './host/craft-compat';
+import type { CraftWritableSignal } from './host/craft-signal';
+/** A guard as the machine stores it: any transition in, truthiness out. */
+export type RuntimeTransitionGuard = (transition: {
+    readonly from: string | undefined;
+    readonly to: string;
+    readonly context: unknown;
+    readonly event: unknown;
+}) => unknown;
+/** What an accepted or refused `transit(...)` reports to its observers. */
+export type MachineTransitionRecord = Readonly<{
+    from: string | undefined;
+    to: string;
+    event: unknown;
+    accepted: boolean;
+}>;
+export type MachineTransitionObserver = (record: MachineTransitionRecord) => void;
+export type MachineRuntime = {
+    readonly context: unknown;
+    readonly currentStep: CraftWritableSignal<string | undefined>;
+    readonly globalGuards: readonly RuntimeTransitionGuard[];
+    readonly stepGuards: Map<string, readonly RuntimeTransitionGuard[]>;
+    readonly injector: Injector;
+    readonly initRegistrations: Array<() => void>;
+    readonly observers: Set<MachineTransitionObserver>;
+    /**
+     * While suspended, the machine's registrations do not run. Restoring a
+     * captured value would otherwise re-fire the very reactions that produced
+     * the transition being replayed, and the machine would fight the replay.
+     */
+    suspended: boolean;
+};
+/**
+ * The step currently being installed (or the step a registered callback was
+ * declared under). `transit(...)` reads it to know its target, which is why the
+ * registration helpers restore it around every deferred callback.
+ */
+export type MachineScope = {
+    readonly runtime: MachineRuntime;
+    readonly target: string;
+};
+export declare function ɵactiveMachineScope(): MachineScope | undefined;
+export declare function ɵrequireMachineScope(helper: string): MachineScope;
+export declare function ɵwithMachineScope<Result>(scope: MachineScope, run: () => Result): Result;
+/**
+ * Drives a generator produced inside a machine (a step installation, a
+ * registered callback, one of the machine factories) through the synchronous
+ * craft runtime, so `yield* SomeService()` resolves against the machine's
+ * injector.
+ */
+export declare function ɵdriveMachineGenerator(value: unknown, injector: Injector): unknown;
+/**
+ * Runs a deferred machine callback: the declaring step is restored so
+ * `transit(...)` resolves to the right target, reads stay untracked (a callback
+ * driven from an effect must not subscribe the effect to whatever its guards
+ * read), and the returned generator — typically `transit(event).pipe(...)` — is
+ * driven through the craft runtime.
+ */
+export declare function ɵrunMachineCallback(scope: MachineScope, run: () => unknown): unknown;
+/**
+ * The value `yield* on$(...)` / `yield* afterRecomputation(...)` /
+ * `yield* initStateMachine(...)` resolve to. It yields one tracked-deps request
+ * (a no-op the craft runtime already understands) so the registration is a
+ * regular member of the step generator's yield chain.
+ */
+export declare function ɵmachineRegistration(): Generator<unknown, void, unknown>;
+/** Registration behind `on$(source, callback)` inside a transitionStep. */
+export declare function ɵregisterMachineSource(source: {
+    subscribe: (callback: (value: never) => void) => {
+        unsubscribe(): void;
+    };
+}, callback: (value: never) => unknown): Generator<unknown, void, unknown>;
+/** Registration behind `afterRecomputation(signal, callback)` inside a step. */
+export declare function ɵregisterMachineRecomputation(source: Signal<unknown>, callback: (value: never) => unknown): Generator<unknown, void, unknown>;
+/** Registration behind `initStateMachine(callback)` inside a step. */
+export declare function ɵregisterMachineInit(callback: () => unknown): Generator<unknown, void, unknown>;
+/**
+ * Evaluates a transition attempt: global guards, then the target step's guards,
+ * then the guards attached to this very `transit(...)` call. A transition to the
+ * current step is a no-op, and the accepted attempt simply publishes the new
+ * step — the last accepted `transit()` wins, with no queue and no priority.
+ */
+export declare function ɵrunTransition(scope: MachineScope, event: unknown, localGuards: readonly RuntimeTransitionGuard[]): Generator<unknown, boolean, unknown>;
+/** Moves the machine to `step` without consulting any guard. */
+export declare function ɵrestoreMachineStep(runtime: MachineRuntime, step: string): void;
+/** Runs `restore` with the machine's registrations muted. */
+export declare function ɵwithSuspendedMachine<Result>(runtime: MachineRuntime, restore: () => Result): Result;
+//# sourceMappingURL=craft-state-machine-runtime.d.ts.map

package/src/lib/craft-state-machine-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft-state-machine-runtime.d.ts","sourceRoot":"","sources":["../../../../../libs/core/src/lib/craft-state-machine-runtime.ts"],"names":[],"mappings":"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"}