@visual-platform/next 0.3.0 → 0.4.0

package/dist/sources.d.ts

@@ -0,0 +1,248 @@
+import { ACTION_BRAND, SOURCE_BRAND, type SourcePlan } from "@visual-platform/contracts";
+/**
+ * App sources (ADR-048, blueprint 67). The app registers its data once; pages reference sources by
+ * name and the SDK resolves — on this Next.js server only — the sources a page actually reads.
+ *
+ *   sources: {
+ *     siteConfig: appConfig,                                   // plain value: read as is
+ *     products: defineSource({ params, resolve: ({ params }) => cms.products(params) }),
+ *   }
+ *
+ * Security by construction: a public source is cached across visitors, so its `context()` only ever
+ * sees the static context; only `visibility: "private"` sources see the request context, and they are
+ * never put in the shared cache.
+ */
+type StandardIssue = {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }> | undefined;
+};
+type StandardResult<O> = {
+    readonly value: O;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<StandardIssue>;
+};
+export type StandardSchema<I = unknown, O = I> = {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<O> | Promise<StandardResult<O>>;
+        readonly types?: {
+            readonly input: I;
+            readonly output: O;
+        } | undefined;
+    };
+};
+type OutputOf<S> = S extends StandardSchema<unknown, infer O> ? O : Record<string, unknown>;
+export declare function validate<O>(schema: StandardSchema<unknown, O>, value: unknown): Promise<{
+    ok: true;
+    value: O;
+} | {
+    ok: false;
+    message: string;
+}>;
+export type SourceVisibility = "public" | "segment" | "private";
+/** Static (cache-safe) context merged with the request context for private sources. */
+export type VisualContextValue = Record<string, unknown>;
+export type SourceResolveArgs<P> = {
+    params: P;
+    /** Content locale of the page. */
+    locale: string;
+    /**
+     * The app context. Public sources see the static context only; segment sources also `segment`;
+     * private sources the full request context (cookies, session…).
+     */
+    context: () => Promise<VisualContextValue>;
+    /** Aborted when the source times out. Pass it to fetch(). */
+    signal: AbortSignal;
+};
+/** Same symbol the CLI checks (contracts SOURCE_BRAND) — `vp sources push` never imports this SDK. */
+declare const SOURCE: typeof SOURCE_BRAND;
+export type SourceDefinition<P = Record<string, unknown>, T = unknown> = {
+    readonly [SOURCE]: true;
+    label?: string | undefined;
+    description?: string | undefined;
+    /** Validates and types the params (defaults apply before the cache key is built). */
+    params?: StandardSchema<unknown, P> | undefined;
+    /** Validates the result (once per cache miss). Also the field list Studio shows after `vp sources push`. */
+    shape?: StandardSchema<unknown, T> | undefined;
+    /** Editor sample and fallback "sample". Never shown on the live site otherwise. */
+    sample?: T | undefined;
+    /** Data the app already has: read as is (no cache, no timeout). */
+    value?: T | undefined;
+    /** The route passes it: <VisualPage data={{ name }} />. Missing → fallback. */
+    provided?: boolean | undefined;
+    resolve?: ((args: SourceResolveArgs<P>) => T | Promise<T>) | undefined;
+    /** Several calls of this source in one render → one call (same order as `params`). */
+    batch?: ((params: P[], args: Omit<SourceResolveArgs<P>, "params">) => Promise<T[]>) | undefined;
+    /** Shared cache (public/segment only). Default: the SDK `revalidate`. Tag `visual:source:<project>:<name>` is always added. */
+    cache?: {
+        revalidate?: number | false | undefined;
+        tags?: string[] | undefined;
+    } | undefined;
+    /** Milliseconds before the fallback is used. Default 1500. */
+    timeout?: number | undefined;
+    /** public (default): same for everyone · segment: per `context.segment` · private: per visitor, never cached. */
+    visibility?: SourceVisibility | undefined;
+    /** Previous name: `vp sources push` renames the Studio record so existing bindings keep working. */
+    renamedFrom?: string | undefined;
+    /**
+     * "server" (default): resolved during the server render. "client": never in the HTML — a component that
+     * `needs` it gets a signed handle and loads it in the browser with `useVisualSource` (per-visitor data on
+     * a cached page). Studio-bound blocks cannot use client sources (they render on the server).
+     */
+    load?: "server" | "client" | undefined;
+    /** For load "client": when the browser fetches it. Default "load". */
+    when?: "load" | "idle" | "visible" | "interaction" | undefined;
+    /** Server source that should not hold the page: its blocks stream in (Suspense) when it arrives. */
+    stream?: boolean | undefined;
+};
+/** What a component that `needs` a client source receives as the prop. Pass it to useVisualSource(). */
+export type VisualSourceHandle = {
+    readonly $vpSource: string;
+    readonly source: string;
+    readonly when: "load" | "idle" | "visible" | "interaction";
+};
+export declare const isSourceHandle: (v: unknown) => v is VisualSourceHandle;
+/** Any value (read as is), a function (resolve shorthand), or defineSource({...}). */
+export type SourceEntry = SourceDefinition<any, any> | ((args: SourceResolveArgs<any>) => unknown) | string | number | boolean | null | readonly unknown[] | Record<string, unknown>;
+export declare function defineSource<S extends StandardSchema | undefined = undefined, T = unknown>(def: Omit<SourceDefinition<OutputOf<S>, T>, typeof SOURCE | "params"> & {
+    params?: S;
+}): SourceDefinition<OutputOf<S>, T>;
+declare const ACTION: typeof ACTION_BRAND;
+export type ActionRunArgs = {
+    /** The Studio event that triggered it (value, detail, itemIndex…), plain data. */
+    event: Record<string, unknown>;
+    /** Full app context (static + request: cookies/session) — actions always run per visitor. */
+    context: () => Promise<VisualContextValue>;
+    locale: string;
+};
+export type ActionDefinition<I = Record<string, unknown>, R = unknown> = {
+    readonly [ACTION]: true;
+    label?: string | undefined;
+    description?: string | undefined;
+    /** Validates the input. Never trust it: check permissions in `run` with the context. */
+    input?: StandardSchema<unknown, I> | undefined;
+    /**
+     * Where input values come from, read on the server from the data the block was rendered with:
+     * { productId: "item.id" } (inside a Repeat) or { plan: "plans.0.id" }. Event values are in `event`.
+     */
+    from?: Record<string, string> | undefined;
+    run: (input: I, args: ActionRunArgs) => R | Promise<R>;
+    /** Sources to refresh after success (shared cache tags + client handles in the browser). */
+    revalidates?: string[] | undefined;
+};
+/** Thrown inside `run` to show a message to the visitor (other errors stay generic). */
+export declare class ActionError extends Error {
+}
+export declare function defineAction<S extends StandardSchema | undefined = undefined, R = unknown>(def: Omit<ActionDefinition<OutputOf<S>, R>, typeof ACTION | "input"> & {
+    input?: S;
+}): ActionDefinition<OutputOf<S>, R>;
+export declare const isActionDefinition: (v: unknown) => v is ActionDefinition;
+export declare const isSourceDefinition: (v: unknown) => v is SourceDefinition;
+/** Normalize an entry: plain values and functions become definitions. */
+export declare function toDefinition(entry: SourceEntry): SourceDefinition;
+export type VisualContextConfig = {
+    /** Cache-safe values (no cookies/headers): currency by locale, feature defaults… */
+    static?: ((a: {
+        locale: string;
+    }) => VisualContextValue | Promise<VisualContextValue>) | undefined;
+    /** Per visitor (cookies, session). Runs only when a page needs it — that page then renders per request. */
+    request?: ((a: {
+        locale: string;
+    }) => VisualContextValue | Promise<VisualContextValue>) | undefined;
+};
+export type SourceErrorCode = "SOURCE_CLIENT_ONLY" | "SOURCE_NOT_REGISTERED" | "SOURCE_NOT_PROVIDED" | "SOURCE_PARAM_INVALID" | "SOURCE_SHAPE_INVALID" | "SOURCE_TIMEOUT" | "SOURCE_FAILED" | "SOURCE_CYCLE";
+export type SourceError = {
+    input: string;
+    source: string;
+    code: SourceErrorCode;
+    message: string;
+};
+/** Cross-request cache (Next `unstable_cache` in the SDK; injectable for tests and other runtimes). */
+export type SourceCache = <T>(fn: () => Promise<T>, keyParts: string[], opts: {
+    revalidate?: number | false | undefined;
+    tags: string[];
+}) => Promise<T>;
+export type ResolverOptions = {
+    projectId: string;
+    sources: Record<string, SourceEntry>;
+    context?: VisualContextConfig | undefined;
+    cache?: SourceCache | undefined;
+    /** Default `revalidate` for shared-cache sources (the SDK passes its own). */
+    revalidate?: number | undefined;
+    timeout?: number | undefined;
+    /** Max sources resolving at once per render. Default 6. */
+    concurrency?: number | undefined;
+    /** Secret for client-source handles (VISUAL_SOURCE_SECRET); resolved lazily, only when a client source is used. */
+    secret?: (() => string) | undefined;
+};
+export type ResolveRequest = {
+    plan: SourcePlan;
+    locale: string;
+    route?: Record<string, unknown> | undefined;
+    query?: Record<string, string | string[] | undefined> | undefined;
+    /** Names the route already passed (prop `data`): never resolved again. */
+    provided?: Record<string, unknown> | undefined;
+    /** Per-request memo (React `cache()` in the SDK) shared by every page/component of the request. */
+    store: Map<string, Promise<unknown>>;
+    /**
+     * Inputs still read once the data known so far is applied (blocks hidden by a showIf that is already
+     * decidable are skipped). Called before each layer; omitted → everything in the plan is needed.
+     */
+    needed?: ((scope: Record<string, unknown>) => Set<string>) | undefined;
+    /** Errors of streamed sources arrive after the response started. */
+    onLateError?: ((e: SourceError) => void) | undefined;
+};
+export type SourceStat = {
+    input: string;
+    source: string;
+    ms: number;
+    cache: "hit" | "miss" | "memo" | "private" | "value" | "client" | "stream" | "skipped" | "error";
+};
+export type ResolveOutcome = {
+    data: Record<string, unknown>;
+    /** Inputs whose fallback is "hide" and whose source failed. */
+    unavailable: Set<string>;
+    errors: SourceError[];
+    /** The request context ran → this render is per visitor (dynamic). */
+    requestContext: string[];
+    /** Streamed inputs (stream: true): render their blocks in <Suspense>. Resolve to undefined on failure. */
+    deferred: Map<string, Promise<unknown>>;
+    /** Per input: time, cache hit/miss… (debug panel). */
+    stats: SourceStat[];
+};
+export declare const sourceTag: (projectId: string, name: string) => string;
+export declare function createSourceResolver(opts: ResolverOptions): {
+    resolve: (r: ResolveRequest) => Promise<ResolveOutcome>;
+    resolveHandle: (token: unknown) => Promise<{
+        ok: true;
+        data: unknown;
+        visibility: SourceVisibility;
+    } | {
+        ok: false;
+        status: number;
+        error: string;
+    }>;
+    resolveDirect: (name: string, rawParams: unknown, locale: string) => Promise<{
+        ok: true;
+        data: unknown;
+    } | {
+        ok: false;
+        status: number;
+        error: string;
+    }>;
+    staticContext: (r: ResolveRequest) => Promise<VisualContextValue>;
+    requestContext: (r: ResolveRequest) => Promise<{
+        [x: string]: unknown;
+    }>;
+    has: (name: string) => boolean;
+    names: () => string[];
+    definition: (name: string) => SourceDefinition<Record<string, unknown>, unknown> | undefined;
+};
+/** Constant-time string compare for webhook secrets. */
+export declare function safeEqual(a: string, b: string): boolean;
+export {};
+//# sourceMappingURL=sources.d.ts.map

package/dist/sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAc,YAAY,EAAa,KAAK,UAAU,EAAwB,MAAM,4BAA4B,CAAC;AAGtI;;;;;;;;;;;;GAYG;AAIH,KAAK,aAAa,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,WAAW,GAAG;QAAE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;KAAE,CAAC,GAAG,SAAS,CAAA;CAAE,CAAC;AAC1I,KAAK,cAAc,CAAC,CAAC,IAAI;IAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;CAAE,CAAC;AAChI,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI;IAC/C,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;QACtF,QAAQ,CAAC,KAAK,CAAC,EAAE;YAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;SAAE,GAAG,SAAS,CAAC;KACxE,CAAC;CACH,CAAC;AACF,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5F,wBAAsB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAQtJ;AAID,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAChE,uFAAuF;AACvF,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEzD,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;IACjC,MAAM,EAAE,CAAC,CAAC;IACV,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC3C,6DAA6D;IAC7D,MAAM,EAAE,WAAW,CAAC;CACrB,CAAC;AAEF,sGAAsG;AACtG,QAAA,MAAM,MAAM,EAAE,OAAO,YAA2B,CAAC;AAEjD,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,OAAO,IAAI;IACvE,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,qFAAqF;IACrF,MAAM,CAAC,EAAE,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC;IAChD,4GAA4G;IAC5G,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC;IAC/C,mFAAmF;IACnF,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;IACvB,mEAAmE;IACnE,KAAK,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IACvE,sFAAsF;IACtF,KAAK,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC;IAChG,+HAA+H;IAC/H,KAAK,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;KAAE,GAAG,SAAS,CAAC;IAC7F,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,iHAAiH;IACjH,UAAU,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC1C,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;;OAIG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACvC,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,CAAC;IAC/D,oGAAoG;IACpG,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC9B,CAAC;AAEF,wGAAwG;AACxG,MAAM,MAAM,kBAAkB,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,aAAa,CAAA;CAAE,CAAC;AACrJ,eAAO,MAAM,cAAc,MAAO,OAAO,KAAG,CAAC,IAAI,kBAAkH,CAAC;AAEpK,sFAAsF;AACtF,MAAM,MAAM,WAAW,GAAG,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,iBAAiB,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAMrL,wBAAgB,YAAY,CAAC,CAAC,SAAS,cAAc,GAAG,SAAS,GAAG,SAAS,EAAE,CAAC,GAAG,OAAO,EACxF,GAAG,EAAE,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,MAAM,GAAG,QAAQ,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,CAAC,CAAA;CAAE,GACrF,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAMlC;AAID,QAAA,MAAM,MAAM,EAAE,OAAO,YAA2B,CAAC;AACjD,MAAM,MAAM,aAAa,GAAG;IAC1B,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,6FAA6F;IAC7F,OAAO,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AACF,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,OAAO,IAAI;IACvE,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,wFAAwF;IACxF,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC;IAC/C;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC1C,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,aAAa,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvD,4FAA4F;IAC5F,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACpC,CAAC;AACF,wFAAwF;AACxF,qBAAa,WAAY,SAAQ,KAAK;CAAG;AAEzC,wBAAgB,YAAY,CAAC,CAAC,SAAS,cAAc,GAAG,SAAS,GAAG,SAAS,EAAE,CAAC,GAAG,OAAO,EACxF,GAAG,EAAE,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,MAAM,GAAG,OAAO,CAAC,GAAG;IAAE,KAAK,CAAC,EAAE,CAAC,CAAA;CAAE,GACnF,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAKlC;AACD,eAAO,MAAM,kBAAkB,MAAO,OAAO,KAAG,CAAC,IAAI,gBAAmG,CAAC;AAEzJ,eAAO,MAAM,kBAAkB,MAAO,OAAO,KAAG,CAAC,IAAI,gBAAmG,CAAC;AAEzJ,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,gBAAgB,CAIjE;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,oFAAoF;IACpF,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,GAAG,SAAS,CAAC;IACnG,2GAA2G;IAC3G,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,GAAG,SAAS,CAAC;CACrG,CAAC;AAIF,MAAM,MAAM,eAAe,GAAG,oBAAoB,GAAG,uBAAuB,GAAG,qBAAqB,GAAG,sBAAsB,GAAG,sBAAsB,GAAG,gBAAgB,GAAG,eAAe,GAAG,cAAc,CAAC;AAC7M,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpG,uGAAuG;AACvG,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEzJ,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC1C,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,mHAAmH;IACnH,MAAM,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;IAClE,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC/C,mGAAmG;IACnG,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACrC;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IACvE,oEAAoE;IACpE,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACtD,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAA;CAAE,CAAC;AAEzK,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,+DAA+D;IAC/D,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,sEAAsE;IACtE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,0GAA0G;IAC1G,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACxC,sDAAsD;IACtD,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,SAAS,cAAe,MAAM,QAAQ,MAAM,WAAyC,CAAC;AAuBnG,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,eAAe;iBAY9B,cAAc,KAAG,OAAO,CAAC,cAAc,CAAC;2BAsJ9B,OAAO,KAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,gBAAgB,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;0BAqB5H,MAAM,aAAa,OAAO,UAAU,MAAM,KAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;uBA/K7I,cAAc;wBAEV,cAAc;;;gBA4LuE,MAAM;;uBAAuE,MAAM;EACnM;AAiBD,wDAAwD;AACxD,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAKvD"}

package/dist/sources.js

@@ -0,0 +1,352 @@
+import { ACTION_BRAND, bindParams, SOURCE_BRAND, stableKey } from "@visual-platform/contracts";
+import { signToken, verifyToken } from "./tokens.js";
+export async function validate(schema, value) {
+    const r = await schema["~standard"].validate(value);
+    if (r.issues) {
+        const first = r.issues[0];
+        const path = first?.path?.map((p) => (typeof p === "object" ? String(p.key) : String(p))).join(".");
+        return { ok: false, message: `${path ? `${path}: ` : ""}${first?.message ?? "invalid"}` };
+    }
+    return { ok: true, value: r.value };
+}
+/** Same symbol the CLI checks (contracts SOURCE_BRAND) — `vp sources push` never imports this SDK. */
+const SOURCE = SOURCE_BRAND;
+export const isSourceHandle = (v) => !!v && typeof v === "object" && typeof v.$vpSource === "string";
+function assertServer(what) {
+    if (typeof window !== "undefined")
+        throw new Error(`[visual] ${what} is server-only — never import your sources in a Client Component.`);
+}
+export function defineSource(def) {
+    assertServer("defineSource");
+    const kinds = [def.value !== undefined, !!def.provided, !!def.resolve].filter(Boolean).length;
+    if (kinds !== 1)
+        throw new Error("[visual] defineSource: give exactly one of value, provided or resolve");
+    if (def.timeout !== undefined && !(def.timeout > 0))
+        throw new Error("[visual] defineSource: timeout must be > 0 ms");
+    return { ...def, [SOURCE]: true };
+}
+// ---------- actions (ADR-048 P4) ----------
+const ACTION = ACTION_BRAND;
+/** Thrown inside `run` to show a message to the visitor (other errors stay generic). */
+export class ActionError extends Error {
+}
+export function defineAction(def) {
+    assertServer("defineAction");
+    if (typeof def.run !== "function")
+        throw new Error("[visual] defineAction: run is required");
+    for (const p of Object.values(def.from ?? {}))
+        if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z0-9_]+){0,9}$/.test(p))
+            throw new Error(`[visual] defineAction: bad path "${p}" in from`);
+    return { ...def, [ACTION]: true };
+}
+export const isActionDefinition = (v) => !!v && typeof v === "object" && v[ACTION] === true;
+export const isSourceDefinition = (v) => !!v && typeof v === "object" && v[SOURCE] === true;
+/** Normalize an entry: plain values and functions become definitions. */
+export function toDefinition(entry) {
+    if (isSourceDefinition(entry))
+        return entry;
+    if (typeof entry === "function")
+        return { [SOURCE]: true, resolve: entry };
+    return { [SOURCE]: true, value: entry };
+}
+export const sourceTag = (projectId, name) => `visual:source:${projectId}:${name}`;
+class Fail extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function limiter(max) {
+    let active = 0;
+    const queue = [];
+    return async (fn) => {
+        if (active >= max)
+            await new Promise((r) => queue.push(r));
+        active++;
+        try {
+            return await fn();
+        }
+        finally {
+            active--;
+            queue.shift()?.();
+        }
+    };
+}
+function withTimeout(ms, run) {
+    const ctl = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => { ctl.abort(); reject(new Fail("SOURCE_TIMEOUT", `no answer after ${ms} ms`)); }, ms);
+    });
+    return Promise.race([run(ctl.signal), timeout]).finally(() => clearTimeout(timer));
+}
+export function createSourceResolver(opts) {
+    assertServer("createVisualNext({ sources })");
+    const defs = new Map(Object.entries(opts.sources).map(([k, v]) => [k, toDefinition(v)]));
+    const run = limiter(opts.concurrency ?? 6);
+    const passthrough = (fn) => fn();
+    const shared = opts.cache ?? passthrough;
+    /** Context loaders memoized in the request store (static ≠ request: the latter makes the page dynamic). */
+    const staticCtx = (r) => memo(r.store, `ctx:static:${r.locale}`, async () => (await opts.context?.static?.({ locale: r.locale })) ?? {});
+    const requestCtx = (r) => memo(r.store, `ctx:request:${r.locale}`, async () => (await opts.context?.request?.({ locale: r.locale })) ?? {});
+    const fullCtx = async (r) => ({ ...(await staticCtx(r)), ...(await requestCtx(r)) });
+    async function resolve(r) {
+        const out = { data: {}, unavailable: new Set(), errors: [], requestContext: [], deferred: new Map(), stats: [] };
+        // An input another input depends on is never streamed (its value is needed for their params).
+        const dependedOn = new Set(r.plan.layers.flat().flatMap((e) => e.dependsOn));
+        const provided = r.provided ?? {};
+        // Context keys used as params: static first, the request context only for keys static lacks.
+        let ctxValues = {};
+        if (r.plan.contextKeys.length) {
+            ctxValues = await staticCtx(r);
+            if (opts.context?.request && r.plan.contextKeys.some((k) => readKey(ctxValues, k) === undefined)) {
+                ctxValues = await fullCtx(r);
+                out.requestContext.push(`context params (${r.plan.contextKeys.join(", ")})`);
+            }
+        }
+        const fallback = (e, def, err) => {
+            out.errors.push(err);
+            if (e.fallback === "hide")
+                out.unavailable.add(e.input);
+            else if (e.fallback === "sample" && def?.sample !== undefined)
+                out.data[e.input] = def.sample;
+        };
+        const remaining = r.plan.layers.flat();
+        for (const [li, layer] of r.plan.layers.entries()) {
+            const jobs = [];
+            // Skip inputs only read by blocks whose showIf is already false (and nothing needed depends on them).
+            let keep = null;
+            if (r.needed && li > 0) {
+                const needed = r.needed({ ...provided, ...out.data });
+                keep = new Set();
+                const byName = new Map(remaining.map((e) => [e.input, e]));
+                const visit = (n) => { if (keep.has(n))
+                    return; keep.add(n); for (const d of byName.get(n)?.dependsOn ?? [])
+                    visit(d); };
+                for (const e of remaining)
+                    if (needed.has(e.input) || e.input.startsWith("$"))
+                        visit(e.input);
+            }
+            for (const e of layer) {
+                remaining.splice(remaining.indexOf(e), 1);
+                if (e.input in provided)
+                    continue;
+                if (keep && !keep.has(e.input)) {
+                    out.stats.push({ input: e.input, source: e.sourceRef, ms: 0, cache: "skipped" });
+                    continue;
+                }
+                const def = defs.get(e.sourceRef);
+                const err = (code, message) => ({ input: e.input, source: e.sourceRef, code, message });
+                if (!def) {
+                    // Legacy "app" inputs (matched by name) may simply not be registered: the route passes them, or not.
+                    if (e.kind === "appSource")
+                        fallback(e, def, err("SOURCE_NOT_REGISTERED", `the app has no source "${e.sourceRef}"`));
+                    continue;
+                }
+                if (def.value !== undefined) {
+                    out.data[e.input] = def.value;
+                    out.stats.push({ input: e.input, source: e.sourceRef, ms: 0, cache: "value" });
+                    continue;
+                }
+                if (def.provided) {
+                    fallback(e, def, err("SOURCE_NOT_PROVIDED", `pass it from the route: data={{ ${e.input} }}`));
+                    continue;
+                }
+                const raw = bindParams(e.params, { locale: r.locale, route: r.route, query: r.query, context: (k) => readKey(ctxValues, k), scope: { ...out.data, ...provided } });
+                let params = raw;
+                if (def.params) {
+                    const v = await validate(def.params, raw);
+                    if (!v.ok) {
+                        fallback(e, def, err("SOURCE_PARAM_INVALID", v.message));
+                        continue;
+                    }
+                    params = v.value;
+                }
+                if (def.load === "client") {
+                    // Only components that `need` it get a signed handle; Studio-bound blocks render on the server.
+                    if (!e.input.startsWith("$")) {
+                        fallback(e, def, err("SOURCE_CLIENT_ONLY", "a load: \"client\" source can only feed a component that `needs` it (useVisualSource)"));
+                        continue;
+                    }
+                    if (!opts.secret) {
+                        fallback(e, def, err("SOURCE_FAILED", "client sources need a secret"));
+                        continue;
+                    }
+                    const token = await signToken({ s: e.sourceRef, p: params, l: r.locale, x: Math.floor(Date.now() / 1000) + 3600 }, opts.secret());
+                    out.data[e.input] = { $vpSource: token, source: e.sourceRef, when: def.when ?? "load" };
+                    out.stats.push({ input: e.input, source: e.sourceRef, ms: 0, cache: "client" });
+                    continue;
+                }
+                const visibility = def.visibility ?? "public";
+                let segment = "";
+                if (visibility === "segment") {
+                    const ctx = await fullCtx(r);
+                    out.requestContext.push(`"${e.input}" (segment)`);
+                    segment = String(ctx.segment ?? "");
+                }
+                if (visibility === "private")
+                    out.requestContext.push(`"${e.input}" (private)`);
+                jobs.push({ e, def, params, key: `src:${e.sourceRef}:${r.locale}:${segment}:${visibility === "private" ? "p:" : ""}${stableKey(params)}` });
+            }
+            // Same source + params in this layer (or earlier in the request) → one call. Batchable sources → one call.
+            const bySource = new Map();
+            for (const j of jobs)
+                if (!r.store.has(j.key))
+                    bySource.set(j.e.sourceRef, [...(bySource.get(j.e.sourceRef) ?? []), j]);
+            for (const [name, list] of bySource) {
+                const def = list[0].def;
+                const unique = [...new Map(list.map((j) => [j.key, j])).values()];
+                if (def.batch && unique.length > 1) {
+                    const all = memo(r.store, `batch:${unique.map((j) => j.key).join("|")}`, () => call(r, name, def, unique.map((j) => j.params), true));
+                    unique.forEach((j, i) => r.store.set(j.key, all.then((rows) => {
+                        if (!Array.isArray(rows) || rows.length !== unique.length)
+                            throw new Fail("SOURCE_FAILED", "batch must return one result per params, in order");
+                        return rows[i];
+                    })));
+                }
+            }
+            const asError = (j, x) => ({ input: j.e.input, source: j.e.sourceRef, code: x instanceof Fail ? x.code : "SOURCE_FAILED", message: x instanceof Error ? x.message : String(x) });
+            await Promise.all(jobs.map(async (j) => {
+                const t0 = Date.now();
+                const hit = r.store.has(j.key);
+                const flag = { executed: false };
+                const p = memo(r.store, j.key, () => call(r, j.e.sourceRef, j.def, j.params, false, flag));
+                if (j.def.stream && !dependedOn.has(j.e.input)) {
+                    // Streamed: the page does not wait; its blocks render in <Suspense> when it arrives.
+                    out.deferred.set(j.e.input, p.then((v) => v, (x) => {
+                        const er = asError(j, x);
+                        r.onLateError?.(er);
+                        return j.e.fallback === "sample" ? j.def.sample : undefined;
+                    }));
+                    if (j.e.fallback === "hide")
+                        out.unavailable.add(j.e.input); // applies only if it fails (value missing)
+                    out.stats.push({ input: j.e.input, source: j.e.sourceRef, ms: 0, cache: "stream" });
+                    return;
+                }
+                try {
+                    out.data[j.e.input] = await p;
+                    const visibility = j.def.visibility ?? "public";
+                    out.stats.push({ input: j.e.input, source: j.e.sourceRef, ms: Date.now() - t0, cache: hit ? "memo" : visibility === "private" ? "private" : flag.executed ? "miss" : "hit" });
+                }
+                catch (x) {
+                    fallback(j.e, j.def, asError(j, x));
+                    out.stats.push({ input: j.e.input, source: j.e.sourceRef, ms: Date.now() - t0, cache: "error" });
+                }
+            }));
+        }
+        return out;
+    }
+    /** One (or one batched) source call: timeout, shape check, shared cache unless private. */
+    function call(r, name, def, params, batched, flag) {
+        const visibility = def.visibility ?? "public";
+        const context = visibility === "private" ? () => fullCtx(r)
+            : visibility === "segment" ? async () => ({ ...(await staticCtx(r)), segment: (await fullCtx(r)).segment })
+                : () => staticCtx(r);
+        const exec = () => run(() => withTimeout(def.timeout ?? opts.timeout ?? 1500, async (signal) => {
+            if (flag)
+                flag.executed = true;
+            const base = { locale: r.locale, context, signal };
+            const result = batched ? await def.batch(params, base) : await def.resolve({ ...base, params: params });
+            if (def.shape) {
+                const rows = batched ? result : [result];
+                for (const row of Array.isArray(rows) ? rows : []) {
+                    const v = await validate(def.shape, row);
+                    if (!v.ok)
+                        throw new Fail("SOURCE_SHAPE_INVALID", v.message);
+                }
+            }
+            return result;
+        }));
+        if (visibility === "private")
+            return exec();
+        const segment = visibility === "segment" ? (fullCtx(r).then((c) => String(c.segment ?? ""))) : Promise.resolve("");
+        return segment.then((seg) => shared(exec, ["visual-source", opts.projectId, name, r.locale, seg, batched ? "batch" : "one", stableKey(params)], {
+            revalidate: def.cache?.revalidate ?? opts.revalidate,
+            tags: [sourceTag(opts.projectId, name), ...(def.cache?.tags ?? [])],
+        }));
+    }
+    /**
+     * Resolve a client-source handle sent back by the browser: verify the signature and expiry, re-validate
+     * the params, then call the source as the server render would (private sources see this visitor's
+     * request context). Null when the handle is not valid for a client source.
+     */
+    async function resolveHandle(token) {
+        if (!opts.secret)
+            return { ok: false, status: 404, error: "no client sources" };
+        const p = await verifyToken(token, opts.secret());
+        if (!p)
+            return { ok: false, status: 403, error: "invalid or expired handle" };
+        const def = defs.get(p.s);
+        if (!def || def.load !== "client" || !def.resolve)
+            return { ok: false, status: 403, error: "not a client source" };
+        let params = p.p;
+        if (def.params) {
+            const v = await validate(def.params, p.p);
+            if (!v.ok)
+                return { ok: false, status: 400, error: v.message };
+            params = v.value;
+        }
+        const r = { plan: { layers: [], contextKeys: [] }, locale: p.l, store: new Map() };
+        try {
+            return { ok: true, data: await call(r, p.s, def, params, false), visibility: def.visibility ?? "public" };
+        }
+        catch (x) {
+            return { ok: false, status: x instanceof Fail && x.code === "SOURCE_TIMEOUT" ? 504 : 502, error: x instanceof Fail ? x.code : "SOURCE_FAILED" };
+        }
+    }
+    /** Resolve one source directly (editor live preview): public sources only, params validated. */
+    async function resolveDirect(name, rawParams, locale) {
+        const def = defs.get(name);
+        if (!def)
+            return { ok: false, status: 404, error: "unknown source" };
+        if ((def.visibility ?? "public") !== "public")
+            return { ok: false, status: 403, error: "only public sources can be previewed" };
+        if (def.value !== undefined)
+            return { ok: true, data: def.value };
+        if (!def.resolve)
+            return { ok: false, status: 400, error: "this source is passed by the route" };
+        let params = rawParams ?? {};
+        if (def.params) {
+            const v = await validate(def.params, params);
+            if (!v.ok)
+                return { ok: false, status: 400, error: v.message };
+            params = v.value;
+        }
+        try {
+            return { ok: true, data: await call({ plan: { layers: [], contextKeys: [] }, locale, store: new Map() }, name, def, params, false) };
+        }
+        catch (x) {
+            return { ok: false, status: 502, error: x instanceof Fail ? x.code : "SOURCE_FAILED" };
+        }
+    }
+    return { resolve, resolveHandle, resolveDirect, staticContext: staticCtx, requestContext: fullCtx, has: (name) => defs.has(name), names: () => [...defs.keys()], definition: (name) => defs.get(name) };
+}
+function memo(store, key, fn) {
+    let p = store.get(key);
+    if (!p) {
+        p = fn();
+        store.set(key, p);
+        p.catch(() => { });
+    }
+    return p;
+}
+function readKey(obj, key) {
+    let cur = obj;
+    for (const seg of key.split(".")) {
+        if (!cur || typeof cur !== "object" || !Object.prototype.hasOwnProperty.call(cur, seg))
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}
+/** Constant-time string compare for webhook secrets. */
+export function safeEqual(a, b) {
+    if (a.length !== b.length || !a)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+//# sourceMappingURL=sources.js.map