octane 0.2.11 → 0.2.13

package/dist/signals/types.d.ts

@@ -1,6 +1,12 @@
-/** Nominal marker for the native signal API; it has no runtime payload. */
+/** Runtime brands for signal handles and legacy query requests. */
 export declare const SIGNAL_HANDLE: unique symbol;
+export declare const SIGNAL_BINDING_READ: unique symbol;
+export declare const SIGNAL_BINDING_SUBSCRIBE: unique symbol;
+export declare const SIGNAL_BINDING_IDENTITY: unique symbol;
 export declare const QUERY_REQUEST: unique symbol;
+export declare const SIGNAL_OWNER_RESOLVE: unique symbol;
+/** A query selector result that deliberately selects no request. */
+export declare const skip: unique symbol;
 export type ConnectionState = 'none' | 'connecting' | 'open' | 'closed';
 interface SnapshotActivity {
     readonly refreshing: boolean;
@@ -11,6 +17,8 @@ interface SnapshotActivity {
 export type SignalSnapshot<T> = SnapshotActivity & ({
     readonly status: 'ready';
     readonly value: T;
+} | {
+    readonly status: 'idle';
 } | {
     readonly status: 'pending';
 } | {
@@ -18,8 +26,13 @@ export type SignalSnapshot<T> = SnapshotActivity & ({
     readonly error: unknown;
 });
 export interface SignalHandle<T> {
-    readonly [SIGNAL_HANDLE]: T;
+    readonly [SIGNAL_HANDLE]: true;
+    readonly [SIGNAL_BINDING_READ]: () => T;
+    /** @internal Observe invalidation; optional teardown replaces the owning scope's final invalidation. */
+    readonly [SIGNAL_BINDING_SUBSCRIBE]: (notify: () => void, onRetire?: () => void) => () => void;
+    readonly [SIGNAL_BINDING_IDENTITY]: () => SignalBindingIdentity;
     readonly key: string;
+    readonly kind: 'signal' | 'derived' | 'async';
     get(): T;
     latest(): T | undefined;
     latest<F>(fallback: F): T | F;
@@ -27,6 +40,11 @@ export interface SignalHandle<T> {
     /** Subscriptions do not deliver an initial notification. */
     subscribe(notify: () => void): () => void;
 }
+/** Stable renderer-facing identity for a direct signal binding. */
+export interface SignalBindingIdentity {
+    readonly scope: 'document' | 'instance';
+    readonly nodeKey: string;
+}
 export interface WritableSignal<T> extends SignalHandle<T> {
     readonly kind: 'signal';
     set(value: T | ((previous: T) => T)): void;
@@ -34,14 +52,39 @@ export interface WritableSignal<T> extends SignalHandle<T> {
 export interface DerivedSignal<T> extends SignalHandle<T> {
     readonly kind: 'derived';
 }
+export interface AttemptRead {
+    <T>(handle$: SignalHandle<T>): Promise<T>;
+}
+export interface DerivedContext {
+    readonly signal: AbortSignal;
+    readonly read: AttemptRead;
+}
+export interface SignalOptions {
+    /** Stable authored identity; the compiler supplies a site when omitted. */
+    readonly key?: string;
+}
+export interface DerivedOptions {
+    /** Assert that the computation returns synchronously and skip async-shape detection. */
+    readonly sync?: boolean;
+}
+export interface QueryOptions {
+    readonly kind?: 'promise' | 'stream';
+}
+export type DerivedCompute<T> = (context: DerivedContext) => T | PromiseLike<T | AsyncIterable<T>> | AsyncIterable<T>;
+export type QueryLoadResult<T> = T | PromiseLike<T | AsyncIterable<T>> | AsyncIterable<T>;
 export interface Resource<T> extends SignalHandle<T> {
     readonly kind: 'async';
     retry(options?: {
         pending?: boolean;
     }): void;
 }
-export interface QueryContext {
+export interface QuerySignal<T> extends Resource<T> {
+    refetch(): void;
+    reset(): void;
+}
+export interface QueryContext<T = unknown> {
     readonly signal: AbortSignal;
+    readonly previous?: T;
 }
 export interface QueryRequest<T> {
     readonly [QUERY_REQUEST]: T;
@@ -99,7 +142,7 @@ export interface ScopeInspection {
     readonly nodes: readonly {
         readonly key: string;
         readonly kind: 'signal' | 'derived' | 'async';
-        readonly status: 'ready' | 'pending' | 'error' | 'unevaluated';
+        readonly status: 'idle' | 'ready' | 'pending' | 'error' | 'unevaluated';
         readonly revision: number;
         readonly subscribers: number;
         readonly retained: boolean;
@@ -127,7 +170,6 @@ export interface Scope {
     readonly retired: boolean;
     signal$<T>(key: string, initial: T): WritableSignal<T>;
     derived$<T>(key: string, compute: (() => T) & (T extends PromiseLike<unknown> ? never : unknown)): DerivedSignal<T>;
-    asyncSignal$<T>(key: string, describe: () => QueryRequest<T>): Resource<T>;
     get<T>(handle$: SignalHandle<T>): T;
     set<T>(handle$: WritableSignal<T>, value: T | ((previous: T) => T)): void;
     isPending(read: () => unknown): boolean;
@@ -138,4 +180,52 @@ export interface Scope {
     inspect(): ScopeInspection;
     dispose(): void;
 }
+export interface OwnerBoundSignal<T> extends SignalHandle<T> {
+    readonly [SIGNAL_OWNER_RESOLVE]: (owner: Scope) => SignalHandle<T>;
+}
+export interface SignalOwnerEnvironment {
+    current(): SignalOwner | null;
+    run<T>(owner: SignalOwner, callback: () => T): T;
+    capture(owner: SignalOwner): <T>(callback: () => T) => T;
+}
+/** A renderer identity is mapped lazily to a Scope only when signals are used. */
+export interface SignalOwnerIdentity {
+    readonly scopeKey: string;
+}
+export interface SignalRendererOwnerIdentity extends SignalOwnerIdentity {
+    readonly documentOwner: SignalOwner;
+    readonly instanceOwner: object;
+    readonly instanceKey: string;
+}
+export type SignalOwner = Scope | SignalOwnerIdentity | SignalRendererOwnerIdentity;
+export interface OptimisticSignal<T> extends WritableSignal<T> {
+}
+export interface OptimisticOptions<T> {
+    /**
+     * Compare authoritative revisions, not client invocation order or optimistic values.
+     * Return a finite positive number only when incoming is newer than current.
+     * Equal or older receipts settle their operation without replacing the source.
+     * The callback must be pure. Omitted policies reuse an existing source policy;
+     * otherwise adoption is unversioned and cannot order concurrent server receipts.
+     */
+    readonly compareAuthority?: (incoming: T, current: T) => number;
+}
+export interface ActionUncertain {
+    readonly status: 'uncertain';
+    readonly operationId: string;
+}
+export interface ActionOperation {
+    readonly id: string;
+    readonly key: string;
+    readonly status: 'pending' | 'confirmed' | 'rejected' | 'uncertain';
+    set<T>(signal$: OptimisticSignal<T>, value: T | ((previous: T) => T)): void;
+    adopt<T>(value: T): void;
+    /** Remove only this operation's intent after a definitive rejection. */
+    reject(): void;
+    uncertain(): ActionUncertain;
+    until(read: () => unknown, options?: {
+        timeout?: number;
+    }): Promise<void>;
+}
+export type SignalAction<F extends (operation: ActionOperation, ...args: any[]) => any> = (...args: F extends (operation: ActionOperation, ...args: infer A) => any ? A : never) => ReturnType<F>;
 export {};

package/dist/signals/types.js

@@ -0,0 +1,20 @@
+const SIGNAL_HANDLE = /* @__PURE__ */ Symbol.for("octane.signal-handle");
+const SIGNAL_BINDING_READ = /* @__PURE__ */ Symbol.for("octane.signal-binding-read");
+const SIGNAL_BINDING_SUBSCRIBE = /* @__PURE__ */ Symbol.for(
+  "octane.signal-binding-subscribe"
+);
+const SIGNAL_BINDING_IDENTITY = /* @__PURE__ */ Symbol.for(
+  "octane.signal-binding-identity"
+);
+const QUERY_REQUEST = /* @__PURE__ */ Symbol.for("octane.query-request");
+const SIGNAL_OWNER_RESOLVE = /* @__PURE__ */ Symbol.for("octane.signal-owner-resolve");
+const skip = /* @__PURE__ */ Symbol.for("octane.query-skip");
+export {
+  QUERY_REQUEST,
+  SIGNAL_BINDING_IDENTITY,
+  SIGNAL_BINDING_READ,
+  SIGNAL_BINDING_SUBSCRIBE,
+  SIGNAL_HANDLE,
+  SIGNAL_OWNER_RESOLVE,
+  skip
+};

package/dist/stream-protocol.d.ts

@@ -1,8 +1,3 @@
-/**
- * Tiny client/server streaming protocol subset shared with the lightweight
- * pre-root hydration event capture. Keep this module dependency-free: loading
- * interaction capture before the main runtime must not initialize DOM tables.
- */
 /** Sentinel <template> attribute marking a pending streamed boundary. */
 export declare const STREAM_BOUNDARY_ATTR = "data-oct-b";
 /** Render-unique token stamped on deferred-hydration owners in a streamed shell. */

package/dist/stream-protocol.js

@@ -1,9 +1,12 @@
+import { isBindingOpenComment } from "./dom-binding-protocol.js";
 const STREAM_BOUNDARY_ATTR = "data-oct-b";
 const HYDRATE_STREAM_TOKEN_ATTR = "data-octane-stream-token";
 function hydrationMarkerMultiplicity(data, open) {
   const marker = open ? "[" : "]";
   if (data === marker) return 1;
   if (open && (data === "[f0" || data === "[f1")) return 1;
+  if (open && (data.startsWith("[b;") || data.startsWith("[f")) && isBindingOpenComment(data))
+    return 1;
   if (data.length < 2 || data.charCodeAt(0) !== marker.charCodeAt(0)) return 0;
   const first = data.charCodeAt(1);
   if (first < 49 || first > 57) return 0;

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

@@ -0,0 +1,60 @@
+import type { EncodedSignalValue, ScopeSeed } from './signals/types.js';
+/** Independent resource/HTML channel identity. Arrival order is never freshness. */
+export interface StreamFrameIdentity {
+    readonly protocol: 1;
+    readonly buildId: string;
+    readonly documentId: string;
+    readonly ownerKey: string;
+    readonly instanceKey: string;
+    readonly nodeKey: string;
+    readonly selectionKey: string;
+    readonly selectionGeneration: number;
+    readonly attempt: number;
+}
+interface StreamFrameBase {
+    readonly identity: StreamFrameIdentity;
+    /** Monotone within one identity and logical channel, beginning at zero. */
+    readonly sequence: number;
+}
+export type StreamedSignalResultFrame = StreamFrameBase & ({
+    readonly channel: 'result';
+    readonly kind: 'open';
+    readonly resource: 'promise' | 'stream';
+} | {
+    readonly channel: 'result';
+    readonly kind: 'value';
+    readonly value: EncodedSignalValue;
+} | {
+    readonly channel: 'result';
+    readonly kind: 'complete';
+} | {
+    readonly channel: 'result';
+    readonly kind: 'error';
+    readonly code: string;
+});
+export type StreamedRegionPlacementFrame = StreamFrameBase & {
+    readonly channel: 'placement';
+    readonly kind: 'html';
+    /** Authoritative monotone revision for the currently selected source. */
+    readonly contentRevision: number;
+    /** A delta is legal only against this exact already-presented revision. */
+    readonly baseRevision?: number;
+    readonly mode: 'full' | 'delta';
+    /** Renderer-owned artifact. Applications do not pass arbitrary HTML here. */
+    readonly html: string;
+    /** Exact values read to produce this range, independent of newer live values. */
+    readonly historicalFrame: ScopeSeed;
+    /** Compiler/bundler style identities that must be ready before reveal. */
+    readonly styles: readonly string[];
+};
+export type StreamedRendererFrame = StreamedSignalResultFrame | StreamedRegionPlacementFrame;
+export declare function isStreamFrameIdentity(value: unknown): value is StreamFrameIdentity;
+/** Strictly validate an untrusted decoded frame before any mailbox or DOM mutation. */
+export declare function isStreamedRendererFrame(value: unknown): value is StreamedRendererFrame;
+export declare function decodeStreamedRendererFrame(json: string): StreamedRendererFrame;
+/** Escape a validated frame for a nonced inline receiver call; never evaluate it as source. */
+export declare function encodeStreamedRendererFrameForScript(frame: StreamedRendererFrame): string;
+export declare function sameStreamFrameIdentity(a: StreamFrameIdentity, b: StreamFrameIdentity): boolean;
+/** Stable local map key only; authority still requires field-by-field comparison. */
+export declare function streamFrameIdentityKey(identity: StreamFrameIdentity): string;
+export {};

package/dist/streamed-signals-protocol.js

@@ -0,0 +1,130 @@
+function isRecord(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return false;
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string") return false;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor.enumerable || !("value" in descriptor)) return false;
+  }
+  return true;
+}
+function isKey(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= 1024;
+}
+function isCounter(value) {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+function hasOnly(record, allowed) {
+  return Object.keys(record).every((key) => allowed.has(key));
+}
+const IDENTITY_KEYS = /* @__PURE__ */ new Set([
+  "protocol",
+  "buildId",
+  "documentId",
+  "ownerKey",
+  "instanceKey",
+  "nodeKey",
+  "selectionKey",
+  "selectionGeneration",
+  "attempt"
+]);
+function isStreamFrameIdentity(value) {
+  if (!isRecord(value) || !hasOnly(value, IDENTITY_KEYS)) return false;
+  return value.protocol === 1 && isKey(value.buildId) && isKey(value.documentId) && isKey(value.ownerKey) && isKey(value.instanceKey) && isKey(value.nodeKey) && isKey(value.selectionKey) && isCounter(value.selectionGeneration) && isCounter(value.attempt);
+}
+function isEncodedSignalValue(value, depth = 0) {
+  if (depth > 100 || !Array.isArray(value) || typeof value[0] !== "string") return false;
+  const tag = value[0];
+  if (tag === "undefined" || tag === "null") return value.length === 1;
+  if (value.length !== 2) return false;
+  if (tag === "boolean") return typeof value[1] === "boolean";
+  if (tag === "string") return typeof value[1] === "string";
+  if (tag === "number") {
+    return value[1] === "-0" || typeof value[1] === "number" && Number.isFinite(value[1]) && !Object.is(value[1], -0);
+  }
+  if (tag === "array") {
+    return Array.isArray(value[1]) && value[1].every((item) => isEncodedSignalValue(item, depth + 1));
+  }
+  if (tag !== "object" || !Array.isArray(value[1])) return false;
+  let previous;
+  for (const entry of value[1]) {
+    if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== "string" || previous !== void 0 && entry[0] <= previous || !isEncodedSignalValue(entry[1], depth + 1)) {
+      return false;
+    }
+    previous = entry[0];
+  }
+  return true;
+}
+function isHistoricalFrame(value) {
+  return isRecord(value) && value.version === 1 && isKey(value.scopeKey) && Array.isArray(value.entries);
+}
+const RESULT_BASE_KEYS = /* @__PURE__ */ new Set(["identity", "sequence", "channel", "kind"]);
+function isStreamedRendererFrame(value) {
+  if (!isRecord(value) || !isStreamFrameIdentity(value.identity) || !isCounter(value.sequence)) {
+    return false;
+  }
+  if (value.channel === "result") {
+    if (value.kind === "open") {
+      return hasOnly(value, /* @__PURE__ */ new Set([...RESULT_BASE_KEYS, "resource"])) && (value.resource === "promise" || value.resource === "stream");
+    }
+    if (value.kind === "value") {
+      return hasOnly(value, /* @__PURE__ */ new Set([...RESULT_BASE_KEYS, "value"])) && isEncodedSignalValue(value.value);
+    }
+    if (value.kind === "error") {
+      return hasOnly(value, /* @__PURE__ */ new Set([...RESULT_BASE_KEYS, "code"])) && isKey(value.code);
+    }
+    return value.kind === "complete" && hasOnly(value, RESULT_BASE_KEYS);
+  }
+  if (value.channel !== "placement" || value.kind !== "html") return false;
+  const allowed = /* @__PURE__ */ new Set([
+    "identity",
+    "sequence",
+    "channel",
+    "kind",
+    "contentRevision",
+    "baseRevision",
+    "mode",
+    "html",
+    "historicalFrame",
+    "styles"
+  ]);
+  if (!hasOnly(value, allowed) || !isCounter(value.contentRevision) || value.mode !== "full" && value.mode !== "delta" || typeof value.html !== "string" || !isHistoricalFrame(value.historicalFrame) || !Array.isArray(value.styles) || !value.styles.every(isKey) || new Set(value.styles).size !== value.styles.length) {
+    return false;
+  }
+  if (value.mode === "delta") return isCounter(value.baseRevision);
+  return value.baseRevision === void 0 || isCounter(value.baseRevision);
+}
+function decodeStreamedRendererFrame(json) {
+  const value = JSON.parse(json);
+  if (!isStreamedRendererFrame(value)) throw new Error("Invalid Octane streamed renderer frame.");
+  return value;
+}
+function encodeStreamedRendererFrameForScript(frame) {
+  if (!isStreamedRendererFrame(frame)) throw new Error("Invalid Octane streamed renderer frame.");
+  return JSON.stringify(frame).replace(/&/g, "\\u0026").replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+function sameStreamFrameIdentity(a, b) {
+  return a.protocol === b.protocol && a.buildId === b.buildId && a.documentId === b.documentId && a.ownerKey === b.ownerKey && a.instanceKey === b.instanceKey && a.nodeKey === b.nodeKey && a.selectionKey === b.selectionKey && a.selectionGeneration === b.selectionGeneration && a.attempt === b.attempt;
+}
+function streamFrameIdentityKey(identity) {
+  return JSON.stringify([
+    identity.protocol,
+    identity.buildId,
+    identity.documentId,
+    identity.ownerKey,
+    identity.instanceKey,
+    identity.nodeKey,
+    identity.selectionKey,
+    identity.selectionGeneration,
+    identity.attempt
+  ]);
+}
+export {
+  decodeStreamedRendererFrame,
+  encodeStreamedRendererFrameForScript,
+  isStreamFrameIdentity,
+  isStreamedRendererFrame,
+  sameStreamFrameIdentity,
+  streamFrameIdentityKey
+};

package/dist/style-values.d.ts

@@ -0,0 +1,3 @@
+export function isUnitlessStyleProp(name: string): boolean;
+export function cssStyleValue(name: string, value: unknown): string;
+export function hyphenateStyleName(name: string): string;

package/dist/style-values.js

@@ -0,0 +1,96 @@
+const UNITLESS_STYLE_PROPS = /* @__PURE__ */ new Set();
+for (const base of [
+  "animationIterationCount",
+  "aspectRatio",
+  "borderImageOutset",
+  "borderImageSlice",
+  "borderImageWidth",
+  "boxFlex",
+  "boxFlexGroup",
+  "boxOrdinalGroup",
+  "columnCount",
+  "columns",
+  "flex",
+  "flexGrow",
+  "flexPositive",
+  "flexShrink",
+  "flexNegative",
+  "flexOrder",
+  "gridArea",
+  "gridRow",
+  "gridRowEnd",
+  "gridRowSpan",
+  "gridRowStart",
+  "gridColumn",
+  "gridColumnEnd",
+  "gridColumnSpan",
+  "gridColumnStart",
+  "fontWeight",
+  "lineClamp",
+  "lineHeight",
+  "opacity",
+  "order",
+  "orphans",
+  "scale",
+  "tabSize",
+  "widows",
+  "zIndex",
+  "zoom",
+  "fillOpacity",
+  "floodOpacity",
+  "stopOpacity",
+  "strokeDasharray",
+  "strokeDashoffset",
+  "strokeMiterlimit",
+  "strokeOpacity",
+  "strokeWidth"
+]) {
+  const c = base.toLowerCase();
+  UNITLESS_STYLE_PROPS.add(c);
+  UNITLESS_STYLE_PROPS.add("webkit" + c);
+  UNITLESS_STYLE_PROPS.add("ms" + c);
+  UNITLESS_STYLE_PROPS.add("moz" + c);
+  UNITLESS_STYLE_PROPS.add("o" + c);
+}
+const unitlessStylePropCache = /* @__PURE__ */ new Map();
+function isUnitlessStyleProp(name) {
+  const cached = unitlessStylePropCache.get(name);
+  if (cached !== void 0) return cached;
+  const result = UNITLESS_STYLE_PROPS.has(name.replaceAll("-", "").toLowerCase());
+  unitlessStylePropCache.set(name, result);
+  return result;
+}
+function cssStyleValue(name, value) {
+  if (typeof value === "number" && value !== 0 && name.charCodeAt(0) !== 45 && !isUnitlessStyleProp(name)) {
+    return value + "px";
+  }
+  return typeof value === "string" ? value.trim() : "" + value;
+}
+function hyphenateStyleName(name) {
+  if (name === "cssFloat") return "float";
+  if (name.charCodeAt(0) === 45) return name;
+  let hasUpper = false;
+  for (let i = 0; i < name.length; i++) {
+    const c = name.charCodeAt(i);
+    if (c >= 65 && c <= 90) {
+      hasUpper = true;
+      break;
+    }
+  }
+  if (!hasUpper) return name;
+  let out = "";
+  for (let i = 0; i < name.length; i++) {
+    const c = name.charCodeAt(i);
+    if (c >= 65 && c <= 90) out += "-" + String.fromCharCode(c + 32);
+    else out += name[i];
+  }
+  if (out.charCodeAt(0) === 109 && out.charCodeAt(1) === 115 && out.charCodeAt(2) === 45) {
+    out = "-" + out;
+  }
+  return out;
+}
+export {
+  cssStyleValue,
+  hyphenateStyleName,
+  isUnitlessStyleProp
+};

package/dist/trusted-html.d.ts

@@ -0,0 +1,17 @@
+/** Nominal proof that the application explicitly accepted this HTML as trusted. */
+declare const trustedHTMLBrand: unique symbol;
+/**
+ * HTML accepted for an intrinsic element's `dangerouslySetInnerHTML` in Strong
+ * mode. The brand is type-only; client rendering and SSR use the ordinary
+ * `{ __html }` representation without a per-element runtime check.
+ */
+export interface TrustedHTML {
+    readonly __html: string;
+    readonly [trustedHTMLBrand]: true;
+}
+/**
+ * Explicitly accept HTML from a trusted source or a sanitizer the application
+ * owns. This function does not sanitize, escape, or validate its input.
+ */
+export declare function trustHTML(html: string): TrustedHTML;
+export {};

package/dist/trusted-html.js

@@ -0,0 +1,6 @@
+function trustHTML(html) {
+  return { __html: html };
+}
+export {
+  trustHTML
+};

package/dist/universal-core.d.ts

@@ -42,6 +42,11 @@ export type UniversalKey = string | number | symbol | bigint;
 export interface UniversalContext<T> {
     readonly $$kind: symbol;
     readonly defaultValue: T;
+    /**
+     * Bumped on every committed provider change; each bump must move the shared
+     * context epoch too (bumpContextEpoch in context-epoch.ts) — the
+     * $$ctxDepsEpoch bail fast path treats an unmoved epoch as "nothing changed".
+     */
     $$version: number;
 }
 export interface UniversalRendererMetadata {
@@ -284,6 +289,7 @@ export type UniversalHostPropEncoding = {
     readonly kind: 'unsupported';
     readonly reason?: string;
 };
+/** One encoding call's context. Codecs may retain it across later props and renders. */
 export interface UniversalHostPropCodecContext<Container = unknown> {
     readonly container: Container;
     readonly renderer: string;