octane 0.2.12 → 0.2.13

package/dist/signals/query-attempt-observer.js

@@ -0,0 +1,41 @@
+let CURRENT_OBSERVER;
+function runWithServerSignalQueryAttemptObserver(owner, observe, createObservations, callback) {
+  const previous = CURRENT_OBSERVER;
+  CURRENT_OBSERVER = { owner, observe, createObservations };
+  try {
+    return callback();
+  } finally {
+    CURRENT_OBSERVER = previous;
+  }
+}
+function serverSignalQueryAttemptObserver(scopeKey) {
+  const context = CURRENT_OBSERVER;
+  if (context === void 0) return;
+  const ownerKey = context.owner.documentOwner.scopeKey;
+  if (scopeKey !== ownerKey && scopeKey !== `${ownerKey}:instance:${context.owner.instanceKey}`) {
+    return;
+  }
+  if (typeof context.createObservations !== "function") {
+    throw new TypeError("A server signal query observer requires an observation factory.");
+  }
+  return context;
+}
+function hasServerSignalQueryAttemptObserver(scopeKey) {
+  return serverSignalQueryAttemptObserver(scopeKey) !== void 0;
+}
+function captureCurrentServerSignalQueryAttemptObserver(scopeKey) {
+  const context = serverSignalQueryAttemptObserver(scopeKey);
+  if (context === void 0) return;
+  return (callback) => runWithServerSignalQueryAttemptObserver(
+    context.owner,
+    context.observe,
+    context.createObservations,
+    callback
+  );
+}
+export {
+  captureCurrentServerSignalQueryAttemptObserver,
+  hasServerSignalQueryAttemptObserver,
+  runWithServerSignalQueryAttemptObserver,
+  serverSignalQueryAttemptObserver
+};

package/dist/signals/query-facade.d.ts

@@ -0,0 +1,3 @@
+import { skip, type QueryContext, type QueryLoadResult, type QueryOptions, type QuerySignal, type SignalOptions } from './types.js';
+export declare function __queryAt<A, T>(site: string | undefined, select: () => A | typeof skip, load: (selection: A, context: QueryContext<T>) => QueryLoadResult<T>, options?: QueryOptions & SignalOptions): QuerySignal<T>;
+export declare function query$<A, T>(select: () => A | typeof skip, load: (selection: A, context: QueryContext<T>) => QueryLoadResult<T>, options?: QueryOptions & SignalOptions): QuerySignal<T>;

package/dist/signals/query-facade.js

@@ -0,0 +1,49 @@
+import { createResourceCellWith } from "./engine.js";
+import { Descriptor, descriptorKey, signalOptionsKey } from "./facade.js";
+import { runWithSignalOwner } from "./owner-context.js";
+import { initializeResource, query as createQueryRequest } from "./requests.js";
+import {
+  skip
+} from "./types.js";
+class QueryDescriptor extends Descriptor {
+  refetch() {
+    this.resolve().retry();
+  }
+  reset() {
+    this.resolve().retry({ pending: true });
+  }
+  retry(options) {
+    this.resolve().retry(options);
+  }
+}
+function __queryAt(site, select, load, options) {
+  if (typeof select !== "function" || typeof load !== "function") {
+    throw new TypeError("query$ requires selector and loader functions.");
+  }
+  const explicit = signalOptionsKey(options);
+  site ??= explicit;
+  const authoredKey = descriptorKey(site, explicit);
+  const key = explicit !== void 0 && (site?.startsWith("g:") || site?.startsWith("i:")) ? site.slice(0, 2) + authoredKey : authoredKey;
+  const request = createQueryRequest(key, load, options);
+  return new QueryDescriptor(
+    key,
+    "async",
+    (owner) => createResourceCellWith(
+      owner,
+      key,
+      () => {
+        const selection = runWithSignalOwner(owner, select);
+        return selection === skip ? skip : request(selection);
+      },
+      initializeResource
+    ),
+    site
+  );
+}
+function query$(select, load, options) {
+  return __queryAt(void 0, select, load, options);
+}
+export {
+  __queryAt,
+  query$
+};

package/dist/signals/read-protocol.d.ts

@@ -1,11 +1,40 @@
-import type { AdoptionFrame, ConnectionState, ScopeSeed } from './types.js';
+import type { AdoptionFrame, ConnectionState, ScopeSeed, SignalHandle } from './types.js';
+import type { SignalCandidateFrame } from './transition-candidate.js';
+import type { ScopedNode } from './graph.js';
+/** Explicit async reads own an observer edge instead of a synchronous graph edge. */
+export declare const SIGNAL_DEPENDENT_NODE: unique symbol;
+export type SignalDependencyNotify = (() => void) & {
+    [SIGNAL_DEPENDENT_NODE]?: ScopedNode;
+};
+/** Only presentation subscriptions participate; public subscribers are never replayed. */
+export declare const NATIVE_TRANSITION_CONSUMER: unique symbol;
+export interface NativeTransitionConsumer {
+    active(): boolean;
+    prepare(): void | NativeTransitionPresentation;
+}
+/** Prepared host work stays private until every participating presentation is ready. */
+export interface NativeTransitionPresentation {
+    validate(): boolean;
+    commit(): void;
+    discard(): void;
+}
+export type NativeTransitionNotify = (() => void) & {
+    [NATIVE_TRANSITION_CONSUMER]?: NativeTransitionConsumer;
+};
+/** Preserve presentation identity when an owner or lifetime wraps a subscription. */
+export declare function forwardNativeTransitionConsumer<T extends () => void>(notify: NativeTransitionNotify, wrapped: T): T;
+/** Lazy renderer registration survives a reentrant synchronous input scope. */
+export declare function registerNativeActionResolver(resolver: () => SignalCandidateFrame | undefined): void;
+export declare function getNativeCandidate(): SignalCandidateFrame | undefined;
+/** Restore before yielding; null suppresses even a newly registered Action resolver. */
+export declare function setNativeCandidateResolver(resolver: (() => SignalCandidateFrame | undefined) | null | undefined): typeof resolver;
 /** Detached DevTools metadata. Reading it must never evaluate or expose a value. */
 export interface NativeReadInspection {
     readonly scopeKey: string;
     readonly key: string;
     readonly read: 'value' | 'latest' | 'snapshot';
     readonly kind: 'signal' | 'derived' | 'async';
-    readonly status: 'ready' | 'pending' | 'error' | 'unevaluated';
+    readonly status: 'idle' | 'ready' | 'pending' | 'error' | 'unevaluated';
     readonly revision: number;
     readonly generation?: number;
     readonly epoch: number;
@@ -42,7 +71,7 @@ export interface NativeReadSource {
 export type NativeReadObserver = (source: NativeReadSource, version: number) => void;
 /** Private protocol implemented on native handles, never inferred from a get method. */
 export declare const NATIVE_DOM_VALUE: unique symbol;
-export declare function readNativeDomValue(value: any): any;
+export declare function readNativeDomValue<T>(value: T): T extends SignalHandle<infer V> ? V : T;
 /** Snapshot values so later writes can diff against the last applied style. */
 export declare function readNativeDomStyle(value: any): any;
 export declare function readNativeDomProps(props: Record<string, unknown>): Record<string, unknown>;

package/dist/signals/read-protocol.js

@@ -1,3 +1,23 @@
+const SIGNAL_DEPENDENT_NODE = /* @__PURE__ */ Symbol("octane.signalDependent");
+const NATIVE_TRANSITION_CONSUMER = /* @__PURE__ */ Symbol("octane.transitionConsumer");
+function forwardNativeTransitionConsumer(notify, wrapped) {
+  const consumer = notify[NATIVE_TRANSITION_CONSUMER];
+  if (consumer) wrapped[NATIVE_TRANSITION_CONSUMER] = consumer;
+  return wrapped;
+}
+let nativeActionResolver;
+let nativeCandidateResolver;
+function registerNativeActionResolver(resolver) {
+  nativeActionResolver = resolver;
+}
+function getNativeCandidate() {
+  return nativeCandidateResolver === void 0 ? nativeActionResolver?.() : nativeCandidateResolver?.();
+}
+function setNativeCandidateResolver(resolver) {
+  const previous = nativeCandidateResolver;
+  nativeCandidateResolver = resolver;
+  return previous;
+}
 let nativeReadObserver = null;
 let nativeWriteGuarded = false;
 const NATIVE_DOM_VALUE = /* @__PURE__ */ Symbol("octane.nativeDomValue");
@@ -79,20 +99,26 @@ function isNativeWriteGuarded() {
 }
 export {
   NATIVE_DOM_VALUE,
+  NATIVE_TRANSITION_CONSUMER,
   NativeAdoptionMiss,
+  SIGNAL_DEPENDENT_NODE,
   beginNativeBatch,
   beginNativeWriteGuard,
   endNativeBatch,
   endNativeWriteGuard,
+  forwardNativeTransitionConsumer,
   getNativeAdoptionResolver,
+  getNativeCandidate,
   getNativeReadObserver,
   isNativeWriteGuarded,
   readNativeDomProps,
   readNativeDomStyle,
   readNativeDomValue,
+  registerNativeActionResolver,
   registerNativeBatchHooks,
   reportNativeRead,
   runNativeBatch,
   setNativeAdoptionResolver,
+  setNativeCandidateResolver,
   setNativeReadObserver
 };

package/dist/signals/requests.d.ts

@@ -1,5 +1,7 @@
-import { ScopedNode, type GraphOwner, type NodeState } from './graph.js';
-import type { QUERY_REQUEST, Query, QueryContext, QueryRequest, SignalSeedEntry } from './types.js';
+import { ScopedNode, type GraphOwner, type CandidateProducer, type NodeState } from './graph.js';
+import { QUERY_REQUEST, skip, type Query, type QueryContext, type QueryRequest, type Resource, type Scope, type SignalSeedEntry } from './types.js';
+import type { StreamFrameIdentity, StreamedSignalResultFrame } from '../streamed-signals-protocol.js';
+import { type ServerSignalQueryAttemptObservations } from './query-attempt-observer.js';
 export interface QueryDefinition {
     readonly key: string;
     readonly kind: 'promise' | 'stream';
@@ -8,10 +10,13 @@ export interface QueryDefinition {
 interface RequestOwner extends GraphOwner {
     readonly requests: Map<string, RequestEntry>;
     readonly queryDefinitions: Map<string, QueryDefinition>;
+    readonly streamedSelections?: Map<string, StreamFrameIdentity>;
+    streamedSelectionReady?(binding: ResourceBinding): void;
+    discardCompletedStreamedSelection?(identity: StreamFrameIdentity): void;
 }
 declare class Request<T> implements QueryRequest<T> {
     readonly definition: QueryDefinition;
-    readonly [QUERY_REQUEST]: T;
+    get [QUERY_REQUEST](): T;
     readonly queryKey: string;
     readonly identity: string;
     readonly argument: unknown;
@@ -23,11 +28,22 @@ export declare function query<A, T>(key: string, load: (argument: A, context: Qu
 export declare function query<A, T>(key: string, load: (argument: A, context: QueryContext) => AsyncIterable<T> | PromiseLike<AsyncIterable<T>>, options: {
     kind: 'stream';
 }): Query<A, T>;
+/**
+ * Create an eagerly selected, explicitly owned query resource. Keys are unique
+ * within the scope; separate resources may share one canonical query request.
+ * Native query$ declarations are the owner-optional authoring API.
+ */
+export declare function createResource<T>(owner: Scope, key: string, describe: () => QueryRequest<T> | typeof skip): Resource<T>;
 interface Attempt {
     entry: RequestEntry | undefined;
     controller: AbortController | undefined;
     iterator: AsyncIterator<unknown> | undefined;
     readonly settled: Promise<void>;
+    readonly generation: number;
+    readonly streamed: boolean;
+    result: unknown;
+    observations: ServerSignalQueryAttemptObservations | undefined;
+    sequence: number;
     resolve(): void;
     hasYielded: boolean;
 }
@@ -43,7 +59,11 @@ export declare class RequestEntry {
         value: unknown;
     });
     get active(): boolean;
+    get attemptGeneration(): number;
+    observe(nodeKey: string): Attempt | undefined;
     start(pending: boolean): void;
+    startStreamed(identity: StreamFrameIdentity): boolean;
+    acceptStreamed(frame: StreamedSignalResultFrame): boolean;
     deliver(): void;
     stopAttempt(): void;
     remove(consumer: ResourceBinding): void;
@@ -52,14 +72,19 @@ export declare class ResourceBinding<T = any> {
     readonly owner: RequestOwner;
     readonly node: ScopedNode<T>;
     private describe;
+    private candidate?;
     private selected;
     private selectedIdentity;
     private retainedRequest;
     private seeded;
     private describedAttempt;
+    private observedAttempt;
+    private pendingObserver;
     private pendingPromise;
     private resolvePending;
-    constructor(owner: RequestOwner, node: ScopedNode<T>, describe: (() => QueryRequest<T>) | undefined, seed?: {
+    private streamedSelection;
+    private selectionAuthority;
+    constructor(owner: RequestOwner, node: ScopedNode<T>, describe: (() => QueryRequest<T> | typeof skip) | undefined, seed?: {
         entry: SignalSeedEntry;
         value: unknown;
     }, retained?: {
@@ -67,18 +92,26 @@ export declare class ResourceBinding<T = any> {
         value: unknown;
     } | undefined);
     private request;
+    forkCandidate(target: ScopedNode<T>): CandidateProducer;
     private compute;
     private state;
     deliver(): void;
     private detach;
+    private observeSelectedAttempt;
+    get authority(): object | undefined;
+    isStreamedSelectionReady(identity: StreamFrameIdentity): boolean;
+    bindStreamedSelection(identity: StreamFrameIdentity): boolean;
+    acceptStreamed(frame: StreamedSignalResultFrame): boolean;
+    failStreamed(identity: StreamFrameIdentity, error: Error): boolean;
     retry(options?: {
         pending?: boolean;
     }): void;
+    adopt(requestKey: string | undefined, value: T): boolean;
     seedRequest(retained?: boolean): SignalSeedEntry['request'];
     acceptsSeed(seed: SignalSeedEntry): boolean;
     dispose(): void;
 }
-export declare function initializeResource<T>(owner: RequestOwner, node: ScopedNode<T>, describe: () => QueryRequest<T>, seed?: {
+export declare function initializeResource<T>(owner: RequestOwner, node: ScopedNode<T>, describe: () => QueryRequest<T> | typeof skip, seed?: {
     entry: SignalSeedEntry;
     value: unknown;
 }, retained?: {