@fusedio/widget-sdk 0.1.0

package/dist/hooks/use-url-signing.js

@@ -0,0 +1,101 @@
+import { useCallback, useEffect, useState } from "react";
+import { useFusedWidgetBridge } from "../bridge";
+import { useParamSubstitution } from "./use-param-substitution";
+/** URL schemes that require signing before fetch. */
+export const SIGNED_URL_SCHEMES = ["s3://", "gs://", "fd://"];
+function needsSigning(url) {
+    return SIGNED_URL_SCHEMES.some((scheme) => url.startsWith(scheme));
+}
+/**
+ * Manual URL signing — returns a stable `signUrl` callback you can call
+ * with any URL. Useful when your component needs to sign URLs imperatively
+ * (e.g. on user click). For reactive media src resolution, use `useMediaSrc`.
+ *
+ * @example
+ * const { signUrl } = useUrlSigning();
+ * const handleDownload = async () => {
+ *   const { signed } = await signUrl("s3://my-bucket/file.csv");
+ *   window.location.href = signed;
+ * };
+ */
+export function useUrlSigning() {
+    const bridge = useFusedWidgetBridge();
+    const signUrl = useCallback((url) => bridge.signUrl(url), [bridge]);
+    return { signUrl };
+}
+/**
+ * Reactively resolve a media `src` URL. Substitutes `$param` tokens first,
+ * then signs S3/GCS/FD URLs. Other URL schemes pass through unchanged.
+ *
+ * @example
+ * const { src, loading, error } = useMediaSrc(props.imageUrl);
+ * if (loading) return <Spinner />;
+ * if (error) return <div>Failed: {error}</div>;
+ * return <img src={src ?? ""} alt="" />;
+ */
+export function useMediaSrc(srcInput) {
+    const bridge = useFusedWidgetBridge();
+    const { value: resolvedSrc, loading: paramLoading } = useParamSubstitution(srcInput);
+    const [displaySrc, setDisplaySrc] = useState(null);
+    const [error, setError] = useState(null);
+    const [signing, setSigning] = useState(false);
+    const [refreshNonce, setRefreshNonce] = useState(0);
+    useEffect(() => {
+        if (paramLoading)
+            return;
+        if (!resolvedSrc) {
+            setDisplaySrc(null);
+            setError(null);
+            setSigning(false);
+            return;
+        }
+        if (!needsSigning(resolvedSrc)) {
+            setDisplaySrc(resolvedSrc);
+            setError(null);
+            setSigning(false);
+            return;
+        }
+        let cancelled = false;
+        setSigning(true);
+        setError(null);
+        bridge
+            .signUrl(resolvedSrc)
+            .then(({ signed }) => {
+            if (cancelled)
+                return;
+            setDisplaySrc(signed ?? resolvedSrc);
+        })
+            .catch((e) => {
+            if (cancelled)
+                return;
+            setError(e instanceof Error ? e.message : "Failed to load media");
+            setDisplaySrc(null);
+        })
+            .finally(() => {
+            if (!cancelled)
+                setSigning(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [bridge, paramLoading, resolvedSrc, refreshNonce]);
+    const refreshSignedUrl = useCallback(async () => {
+        if (!resolvedSrc || !needsSigning(resolvedSrc)) {
+            return resolvedSrc ?? null;
+        }
+        const { signed } = await bridge.signUrl(resolvedSrc);
+        const next = signed ?? resolvedSrc;
+        setDisplaySrc(next);
+        setError(null);
+        setRefreshNonce((n) => n + 1);
+        return next;
+    }, [bridge, resolvedSrc]);
+    return {
+        src: displaySrc,
+        loading: paramLoading || signing,
+        error,
+        refreshSignedUrl,
+        resolvedSrc,
+        needsSigning: Boolean(resolvedSrc && needsSigning(resolvedSrc)),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @fusedio/widget-sdk — public surface.
+ *
+ * This SDK has two parts:
+ *
+ *   1. **Provider contract** — `FusedWidgetBridge` + `FusedWidgetBridgeContext`.
+ *      Hosts (the Fused workbench, the catalog-template test harness, any
+ *      future embedder) implement the bridge and provide it via the context.
+ *
+ *   2. **Hooks** — every API a component author needs. Hooks read the bridge
+ *      from context and delegate state management to it. Authors call hooks;
+ *      the bridge is invisible to them.
+ *
+ * Catalog components depend only on these hooks and types. They do not need
+ * to know about Jotai, BroadcastChannel internals, or the workbench source.
+ */
+export * from "./protocol";
+export * from "./bridge";
+export * from "./form";
+export * from "./types";
+export { defineComponent, type CatalogComponentDefinition, } from "./define-component";
+export { defineCatalog, type CatalogDefinition, type CatalogDefinitionBase, type CatalogDefinitionWithSkill, } from "./define-catalog";
+export { useFusedParam } from "./hooks/use-fused-param";
+export { useCanvasParams } from "./hooks/use-canvas-params";
+export { useAllowedSources } from "./hooks/use-allowed-sources";
+export { useAllowedUdfNames } from "./hooks/use-allowed-udf-names";
+export { useParamSubstitution } from "./hooks/use-param-substitution";
+export { useUdfOutputByName, useRequestUdfReexecute, useUdfDataFrameSample, useUdfColumnValue, useUdfColumnValues, isUdfQuery, parseUdfColumnQuery, type ParsedUdfQuery, type UseUdfDataFrameSampleOptions, type UseUdfDataFrameSampleResult, type UseUdfColumnValueResult, type UseUdfColumnValuesResult, } from "./hooks/use-udf-output";
+export { useDuckDbSqlQuery, useDuckDbSqlQueryPreprocessing, useVfsRegistration, type UseDuckDbSqlQueryOptions, type UseDuckDbSqlQueryResult, type UseDuckDbSqlQueryPreprocessingResult, } from "./hooks/use-duckdb-sql";
+export { useUrlSigning, useMediaSrc, SIGNED_URL_SCHEMES, type UseMediaSrcResult, } from "./hooks/use-url-signing";
+export { useUploadAccessCheck, type UploadAccessState, } from "./hooks/use-upload-access-check";
+export { useJsonUiLog, useJsonUiLogs, useJsonUiLogClear, } from "./hooks/use-json-ui-log";
+export { useJsonUiUdfInfo } from "./hooks/use-json-ui-udf-info";
+export { useJsonUiEdgeAnimation } from "./hooks/use-json-ui-edge-animation";
+export * from "./utils/sql-placeholders";

package/dist/index.js

@@ -0,0 +1,40 @@
+/**
+ * @fusedio/widget-sdk — public surface.
+ *
+ * This SDK has two parts:
+ *
+ *   1. **Provider contract** — `FusedWidgetBridge` + `FusedWidgetBridgeContext`.
+ *      Hosts (the Fused workbench, the catalog-template test harness, any
+ *      future embedder) implement the bridge and provide it via the context.
+ *
+ *   2. **Hooks** — every API a component author needs. Hooks read the bridge
+ *      from context and delegate state management to it. Authors call hooks;
+ *      the bridge is invisible to them.
+ *
+ * Catalog components depend only on these hooks and types. They do not need
+ * to know about Jotai, BroadcastChannel internals, or the workbench source.
+ */
+// ── Part 1: Provider contract ────────────────────────────────────────────────
+export * from "./protocol";
+export * from "./bridge";
+export * from "./form";
+// ── Part 2: Hook types ───────────────────────────────────────────────────────
+export * from "./types";
+// ── Part 3: Catalog component registration ───────────────────────────────────
+export { defineComponent, } from "./define-component";
+export { defineCatalog, } from "./define-catalog";
+// ── Part 2: Hooks ────────────────────────────────────────────────────────────
+export { useFusedParam } from "./hooks/use-fused-param";
+export { useCanvasParams } from "./hooks/use-canvas-params";
+export { useAllowedSources } from "./hooks/use-allowed-sources";
+export { useAllowedUdfNames } from "./hooks/use-allowed-udf-names";
+export { useParamSubstitution } from "./hooks/use-param-substitution";
+export { useUdfOutputByName, useRequestUdfReexecute, useUdfDataFrameSample, useUdfColumnValue, useUdfColumnValues, isUdfQuery, parseUdfColumnQuery, } from "./hooks/use-udf-output";
+export { useDuckDbSqlQuery, useDuckDbSqlQueryPreprocessing, useVfsRegistration, } from "./hooks/use-duckdb-sql";
+export { useUrlSigning, useMediaSrc, SIGNED_URL_SCHEMES, } from "./hooks/use-url-signing";
+export { useUploadAccessCheck, } from "./hooks/use-upload-access-check";
+export { useJsonUiLog, useJsonUiLogs, useJsonUiLogClear, } from "./hooks/use-json-ui-log";
+export { useJsonUiUdfInfo } from "./hooks/use-json-ui-udf-info";
+export { useJsonUiEdgeAnimation } from "./hooks/use-json-ui-edge-animation";
+// ── Pure utilities (re-exported for advanced workbench paths) ────────────────
+export * from "./utils/sql-placeholders";

package/dist/protocol.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The Fused workbench listens on this BroadcastChannel for parameter updates
+ * from all components — both built-in and 3rd-party catalogs. The channel name
+ * is part of the public protocol; do not change it without coordinating with
+ * the workbench listener and all in-the-wild catalogs.
+ */
+export declare const PARAMETER_BROADCAST_CHANNEL = "parameter-updates";
+/**
+ * Discriminator for parameter messages on the BroadcastChannel.
+ *
+ * - `PARAM`    — generic parameter value update (the most common kind)
+ * - `RANGE`    — range filter from a slider or histogram: `{ min, max }`
+ * - `VIEWPORT` — map viewport bounds: `{ west, south, east, north }`
+ * - `CLEAR`    — clear a parameter for this source (value will be `null`)
+ */
+export declare enum ParameterMessageType {
+    PARAM = "param",
+    RANGE = "range",
+    VIEWPORT = "viewport",
+    CLEAR = "clear"
+}
+/**
+ * Canonical message shape posted on the parameter-updates BroadcastChannel.
+ * All param messages — inbound and outbound — use this shape.
+ *
+ * The Fused workbench attaches additional source-identification fields
+ * (`sourceUdfUniqueId`, `sourceUdfName`, `sourceTabId`) for edge-based
+ * routing; catalog code does not need to construct these directly — use
+ * the `bridge.params.set()` method (or the `useFusedParam` hook).
+ */
+export interface StandardMessage {
+    type: ParameterMessageType;
+    /** Canvas parameter name, e.g. `"selected_city"`. */
+    parameter: string;
+    /** Value payload; `null` for `CLEAR`. */
+    values: unknown;
+}
+/** Type guard that verifies an unknown object is a valid StandardMessage. */
+export declare function isStandardMessage(msg: unknown): msg is StandardMessage;

package/dist/protocol.js

@@ -0,0 +1,32 @@
+/**
+ * The Fused workbench listens on this BroadcastChannel for parameter updates
+ * from all components — both built-in and 3rd-party catalogs. The channel name
+ * is part of the public protocol; do not change it without coordinating with
+ * the workbench listener and all in-the-wild catalogs.
+ */
+export const PARAMETER_BROADCAST_CHANNEL = "parameter-updates";
+/**
+ * Discriminator for parameter messages on the BroadcastChannel.
+ *
+ * - `PARAM`    — generic parameter value update (the most common kind)
+ * - `RANGE`    — range filter from a slider or histogram: `{ min, max }`
+ * - `VIEWPORT` — map viewport bounds: `{ west, south, east, north }`
+ * - `CLEAR`    — clear a parameter for this source (value will be `null`)
+ */
+export var ParameterMessageType;
+(function (ParameterMessageType) {
+    ParameterMessageType["PARAM"] = "param";
+    ParameterMessageType["RANGE"] = "range";
+    ParameterMessageType["VIEWPORT"] = "viewport";
+    ParameterMessageType["CLEAR"] = "clear";
+})(ParameterMessageType || (ParameterMessageType = {}));
+/** Type guard that verifies an unknown object is a valid StandardMessage. */
+export function isStandardMessage(msg) {
+    if (typeof msg !== "object" || msg === null)
+        return false;
+    const m = msg;
+    return (typeof m.type === "string" &&
+        Object.values(ParameterMessageType).includes(m.type) &&
+        typeof m.parameter === "string" &&
+        "values" in m);
+}

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The props every catalog component receives.
+ *
+ * The json-ui renderer calls your component as:
+ * ```tsx
+ * <MyComponent element={{ type: "my-type", props: { ...yourProps } }} />
+ * ```
+ *
+ * Always destructure values from `element.props`; never spread `element` itself.
+ *
+ * @example
+ * interface Props { param: string; label?: string; step?: number }
+ * export function MyWidget({ element }: ComponentRenderProps<Props>) {
+ *   const { param, label = "Value", step = 1 } = element.props;
+ *   const { value, setValue } = useFusedParam({ param, defaultValue: 0 });
+ *   return <button onClick={() => setValue(value + step)}>{label}: {value}</button>;
+ * }
+ */
+export interface ComponentRenderProps<P = Record<string, unknown>> {
+    element: {
+        type: string;
+        props: P;
+        key?: string;
+        children?: unknown[];
+        visible?: boolean;
+    };
+}
+/**
+ * Options for `useFusedParam`. The type parameter `T` is inferred from
+ * `defaultValue` — pass typed defaults like `0`, `""`, `[] as Foo[]` to
+ * narrow the return type.
+ */
+export interface UseFusedParamOptions<T> {
+    /**
+     * Canvas parameter name (kebab-case by convention).
+     * If undefined or empty, the hook behaves as local state only (no broadcast).
+     */
+    param?: string;
+    /** Debounce delay in ms between `setValue()` and the broadcast. Default: 300. */
+    debounceMs?: number;
+    /** Accept incoming canvas values but never broadcast outgoing ones. */
+    readOnly?: boolean;
+    /** Starting value. Type `T` is inferred from this. */
+    defaultValue: T;
+    /**
+     * Broadcast `defaultValue` on mount if no canvas value exists. Default: true.
+     * Empty-string defaults are never broadcast (guarded internally).
+     */
+    broadcastDefaultValue?: boolean;
+    /** Custom type guard run on incoming values after `preprocess`. */
+    validate?: (value: unknown) => value is T;
+    /**
+     * Coerce raw incoming values before validation. The default preprocessor
+     * coerces strings to string; all other types pass through unchanged.
+     */
+    preprocess?: (value: unknown) => T;
+}
+/** Return value of `useFusedParam`. */
+export interface UseFusedParamReturn<T> {
+    /** Current value — updated from canvas, form, or local `setValue()`. */
+    value: T;
+    /** Set locally and broadcast to canvas (debounced). Starts edge animation. */
+    setValue(newValue: T): void;
+    /** Broadcast current value immediately, bypassing the debounce timer. */
+    broadcastNow(): void;
+    /** Reset to `newValue` locally and send a CLEAR message to the canvas. */
+    clearValue(newValue: T): void;
+}
+export interface ParamSubstitutionOptions {
+    /**
+     * If `true`, unresolved `$param` tokens are left as-is instead of being
+     * replaced with empty string. Useful for SQL template fragments.
+     */
+    preserveMissingParams?: boolean;
+}
+export interface ParamSubstitutionResult {
+    /** Template with all resolved tokens replaced. */
+    value: string;
+    /**
+     * True while `{{udf_name}}` data is being fetched. Always `false` for
+     * pure-`$param` templates.
+     */
+    loading: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/sql-placeholders.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Pure parsing/substitution utilities for widget SQL strings.
+ *
+ * Two syntaxes are recognised:
+ *   - `$param_name` — canvas/form param reference, substituted inline.
+ *   - `{{udf_name}}` or `{{udf_name?k=v&k2=v2}}` — UDF Parquet placeholder,
+ *     optionally with override params. Override suffixes accept `&` or `,`
+ *     as separators and URL-decoded keys/values.
+ *
+ * These helpers are also used by the host (workbench bridge) for VFS
+ * registration; lifting them into the SDK keeps a single source of truth.
+ */
+export declare const SQL_PARAM_REGEX: RegExp;
+export declare const SQL_SOURCE_PLACEHOLDER_REGEX: RegExp;
+/**
+ * Matches `'scheme://...'` literals inside a SQL string. We deliberately
+ * limit to single-quoted string literals so that bare identifiers or
+ * comments containing a URL-like token aren't treated as paths to sign.
+ */
+export declare const SIGNABLE_URL_LITERAL_REGEX: RegExp;
+export declare function escapeSqlValue(value: unknown): string;
+/**
+ * Substitute `$param_name` references directly into the SQL string. When a
+ * `$param` lives inside a single-quoted string literal, only the raw
+ * quote-escaped value is spliced in so we don't add nested quotes.
+ */
+export declare function substituteSqlParams(sql: string, paramValues: Record<string, unknown>): string;
+/** Extract all SQL parameter names from `$param_name` references. */
+export declare function extractSqlParams(sql: string): string[];
+export interface SqlUdfPlaceholder {
+    /** Full match text including braces, e.g. `{{udf?city=NYC}}` */
+    match: string;
+    /** UDF name, e.g. `udf` */
+    name: string;
+    /**
+     * Parsed override params if the placeholder contains a `?...` suffix,
+     * otherwise `null`. Values are raw (URL-decoded) strings — they may still
+     * contain `$param` references that need canvas/form resolution.
+     */
+    overrides: Record<string, string> | null;
+    start: number;
+    end: number;
+}
+export declare function parseOverridesString(rawOverrides: string | undefined): Record<string, string> | null;
+/**
+ * Parse every `{{udf}}` or `{{udf?k=v&k2=v2}}` placeholder. Returns
+ * occurrences in source order, preserving duplicates so callers can
+ * substitute by start/end offsets.
+ */
+export declare function parseSqlUdfPlaceholders(sql: string): SqlUdfPlaceholder[];
+/**
+ * Extract every signable URL appearing as a single-quoted string literal,
+ * deduped, in first-occurrence order.
+ */
+export declare function extractSignableUrls(sql: string): string[];
+/**
+ * Replace every signable URL literal in `sql` with its signed counterpart
+ * from `signedMap`. Literals whose URL is missing from the map are left
+ * untouched.
+ */
+export declare function rewriteSignedUrls(sql: string, signedMap: Record<string, string>): string;
+/** Return the param name if `value` is a single `$name` reference. */
+export declare function getDollarRefName(value: string): string | null;
+export interface ResolvedOverrideValue {
+    value: string;
+    unresolved: boolean;
+}
+/**
+ * Resolve a raw override value. If the entire value is a `$name` reference,
+ * substitute the param value; otherwise return verbatim. When the param is
+ * missing entirely (key not in the map), marks the result as `unresolved`
+ * so callers can keep the placeholder pending until upstream params settle.
+ */
+export declare function resolveOverrideValue(rawValue: string, paramValues: Record<string, unknown>): ResolvedOverrideValue;
+/**
+ * Canonical registry key for `(name, overrides)`. Bare placeholders use the
+ * name alone; overrides are sorted by key and joined with `&`.
+ */
+export declare function canonicalOverrideKey(overrides: Record<string, string>): string;
+export declare function computePlaceholderKey(name: string, overrides: Record<string, string> | null): string;

package/dist/utils/sql-placeholders.js

@@ -0,0 +1,204 @@
+/**
+ * Pure parsing/substitution utilities for widget SQL strings.
+ *
+ * Two syntaxes are recognised:
+ *   - `$param_name` — canvas/form param reference, substituted inline.
+ *   - `{{udf_name}}` or `{{udf_name?k=v&k2=v2}}` — UDF Parquet placeholder,
+ *     optionally with override params. Override suffixes accept `&` or `,`
+ *     as separators and URL-decoded keys/values.
+ *
+ * These helpers are also used by the host (workbench bridge) for VFS
+ * registration; lifting them into the SDK keeps a single source of truth.
+ */
+export const SQL_PARAM_REGEX = /\$([a-zA-Z_][a-zA-Z0-9_]*)/g;
+export const SQL_SOURCE_PLACEHOLDER_REGEX = /\{\{(\w+)(?:\?([^}]*))?\}\}/g;
+/**
+ * Matches `'scheme://...'` literals inside a SQL string. We deliberately
+ * limit to single-quoted string literals so that bare identifiers or
+ * comments containing a URL-like token aren't treated as paths to sign.
+ */
+export const SIGNABLE_URL_LITERAL_REGEX = /'((?:s3|gs|fd):\/\/[^'\n]+)'/g;
+export function escapeSqlValue(value) {
+    if (value == null)
+        return "''";
+    if (typeof value === "number" && !Number.isNaN(value))
+        return String(value);
+    if (typeof value === "boolean")
+        return value ? "TRUE" : "FALSE";
+    const str = String(value);
+    return `'${str.replace(/'/g, "''")}'`;
+}
+function isInsideSingleQuotedSqlString(sql, offset) {
+    let inString = false;
+    for (let i = 0; i < offset; i++) {
+        if (sql[i] !== "'")
+            continue;
+        if (inString && sql[i + 1] === "'") {
+            i++;
+            continue;
+        }
+        inString = !inString;
+    }
+    return inString;
+}
+/**
+ * Substitute `$param_name` references directly into the SQL string. When a
+ * `$param` lives inside a single-quoted string literal, only the raw
+ * quote-escaped value is spliced in so we don't add nested quotes.
+ */
+export function substituteSqlParams(sql, paramValues) {
+    return sql.replace(SQL_PARAM_REGEX, (_match, paramName, offset) => {
+        const value = paramValues[paramName];
+        const raw = value == null ? "" : String(value);
+        if (isInsideSingleQuotedSqlString(sql, offset)) {
+            return raw.replace(/'/g, "''");
+        }
+        return escapeSqlValue(value);
+    });
+}
+/** Extract all SQL parameter names from `$param_name` references. */
+export function extractSqlParams(sql) {
+    const seen = new Set();
+    const out = [];
+    SQL_PARAM_REGEX.lastIndex = 0;
+    for (const m of sql.matchAll(SQL_PARAM_REGEX)) {
+        const name = m[1];
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        out.push(name);
+    }
+    return out;
+}
+export function parseOverridesString(rawOverrides) {
+    if (!rawOverrides)
+        return null;
+    const result = {};
+    let parsedAny = false;
+    for (const pair of rawOverrides.split(/[&,]/)) {
+        if (!pair)
+            continue;
+        const eq = pair.indexOf("=");
+        if (eq === -1)
+            continue;
+        const rawKey = pair.slice(0, eq);
+        const rawValue = pair.slice(eq + 1);
+        let key;
+        let value;
+        try {
+            key = decodeURIComponent(rawKey);
+            value = decodeURIComponent(rawValue);
+        }
+        catch {
+            key = rawKey;
+            value = rawValue;
+        }
+        if (!key)
+            continue;
+        result[key] = value;
+        parsedAny = true;
+    }
+    return parsedAny ? result : null;
+}
+/**
+ * Parse every `{{udf}}` or `{{udf?k=v&k2=v2}}` placeholder. Returns
+ * occurrences in source order, preserving duplicates so callers can
+ * substitute by start/end offsets.
+ */
+export function parseSqlUdfPlaceholders(sql) {
+    const placeholders = [];
+    let match;
+    SQL_SOURCE_PLACEHOLDER_REGEX.lastIndex = 0;
+    while ((match = SQL_SOURCE_PLACEHOLDER_REGEX.exec(sql)) !== null) {
+        const [fullMatch, name, rawOverrides] = match;
+        placeholders.push({
+            match: fullMatch,
+            name,
+            overrides: parseOverridesString(rawOverrides),
+            start: match.index,
+            end: match.index + fullMatch.length,
+        });
+    }
+    return placeholders;
+}
+/**
+ * Extract every signable URL appearing as a single-quoted string literal,
+ * deduped, in first-occurrence order.
+ */
+export function extractSignableUrls(sql) {
+    if (!sql)
+        return [];
+    const seen = new Set();
+    const out = [];
+    SIGNABLE_URL_LITERAL_REGEX.lastIndex = 0;
+    let match;
+    while ((match = SIGNABLE_URL_LITERAL_REGEX.exec(sql)) !== null) {
+        const url = match[1];
+        if (!seen.has(url)) {
+            seen.add(url);
+            out.push(url);
+        }
+    }
+    return out;
+}
+/**
+ * Replace every signable URL literal in `sql` with its signed counterpart
+ * from `signedMap`. Literals whose URL is missing from the map are left
+ * untouched.
+ */
+export function rewriteSignedUrls(sql, signedMap) {
+    if (!sql)
+        return sql;
+    return sql.replace(SIGNABLE_URL_LITERAL_REGEX, (literal, url) => {
+        const signed = signedMap[url];
+        if (!signed)
+            return literal;
+        return `'${signed}'`;
+    });
+}
+// ============================================================================
+// Override-param resolution
+// ============================================================================
+const DOLLAR_REF_RE = /^\$([a-zA-Z_][a-zA-Z0-9_]*)$/;
+/** Return the param name if `value` is a single `$name` reference. */
+export function getDollarRefName(value) {
+    const trimmed = value.trim();
+    const m = DOLLAR_REF_RE.exec(trimmed);
+    return m ? m[1] : null;
+}
+/**
+ * Resolve a raw override value. If the entire value is a `$name` reference,
+ * substitute the param value; otherwise return verbatim. When the param is
+ * missing entirely (key not in the map), marks the result as `unresolved`
+ * so callers can keep the placeholder pending until upstream params settle.
+ */
+export function resolveOverrideValue(rawValue, paramValues) {
+    const m = DOLLAR_REF_RE.exec(rawValue);
+    if (!m) {
+        return { value: rawValue, unresolved: false };
+    }
+    const name = m[1];
+    if (!(name in paramValues)) {
+        return { value: rawValue, unresolved: true };
+    }
+    const resolved = paramValues[name];
+    if (resolved == null) {
+        return { value: "", unresolved: false };
+    }
+    return { value: String(resolved), unresolved: false };
+}
+/**
+ * Canonical registry key for `(name, overrides)`. Bare placeholders use the
+ * name alone; overrides are sorted by key and joined with `&`.
+ */
+export function canonicalOverrideKey(overrides) {
+    return Object.keys(overrides)
+        .sort()
+        .map((k) => `${k}=${overrides[k]}`)
+        .join("&");
+}
+export function computePlaceholderKey(name, overrides) {
+    if (!overrides)
+        return name;
+    return `${name}#${canonicalOverrideKey(overrides)}`;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@fusedio/widget-sdk",
+  "version": "0.1.0",
+  "description": "SDK for building custom json-ui components for the Fused workbench",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "bundle": "tsc --noEmit && esbuild src/index.ts --bundle --outfile=dist/bundle.js --format=esm --platform=browser --external:react --external:react/jsx-runtime --external:zod --minify",
+    "prepublishOnly": "bun run clean && bun run build && bun run bundle"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "esbuild": "0.25.10",
+    "typescript": "^5.4.3",
+    "@types/react": "^18.3.11",
+    "zod": "^4.3.6"
+  }
+}