gazetta 0.6.0 → 0.8.0

package/dist/deploy/errors.js

@@ -0,0 +1,82 @@
+/**
+ * Error taxonomy for the DeployAdapter Pattern 1 Provider surface.
+ *
+ * Cut 1 of the deploy contract. Per ADR-0004 Universal Provider
+ * Requirement #6 ("independent error taxonomy"), every Provider
+ * surface declares its own error classes for runtime branching.
+ *
+ * Adapters translate platform-SDK errors into these classes; the CLI
+ * catches `DeployError` and surfaces the `adapter` field plus a
+ * human-readable message. Debug logs include the underlying cause.
+ *
+ * Reference: `.claude/rules/design-deploy.md` "Error taxonomy" section.
+ */
+/**
+ * Base class for all deploy errors. Carries the adapter name so the
+ * CLI can surface "Cloudflare Workers deploy failed: ..." instead of
+ * a context-free error message.
+ */
+export class DeployError extends Error {
+    adapter;
+    constructor(message, adapter) {
+        super(message);
+        this.name = 'DeployError';
+        this.adapter = adapter;
+    }
+}
+/**
+ * Raised at factory construction (synchronous) when operator-supplied
+ * options are missing required fields or malformed. Surfaces in the
+ * IDE / at admin boot, not at deploy time.
+ *
+ * Example: `cloudflareWorkersDeploy({ name: 'foo' })` without
+ * `apiToken` throws `DeployConfigError` because the platform SDK
+ * can't proceed without credentials.
+ */
+export class DeployConfigError extends DeployError {
+    constructor(message, adapter) {
+        super(message, adapter);
+        this.name = 'DeployConfigError';
+    }
+}
+/**
+ * Raised at `execute()` time when the platform rejects credentials.
+ * Adapters wrap platform-SDK auth failures (401 / 403 from the
+ * platform's API) in this class so operators see a consistent
+ * "credentials rejected" surface regardless of which platform.
+ */
+export class DeployAuthError extends DeployError {
+    constructor(message, adapter) {
+        super(message, adapter);
+        this.name = 'DeployAuthError';
+    }
+}
+/**
+ * Raised at `execute()` time when the network or platform SDK call
+ * fails for transport reasons (timeout, DNS, 5xx from platform,
+ * unexpected protocol error). Distinct from auth failures because
+ * the operator's remediation differs: auth = check credentials;
+ * transport = retry or investigate platform status.
+ */
+export class DeployTransportError extends DeployError {
+    constructor(message, adapter) {
+        super(message, adapter);
+        this.name = 'DeployTransportError';
+    }
+}
+/**
+ * Raised at `execute()` time when the adapter expects published
+ * content (e.g., a static-host adapter that reads from
+ * `target.storage`) but storage is empty.
+ *
+ * Per Q4 lock: the CLI doesn't gate on prior publish — adapters that
+ * need bytes surface this error themselves. Operator's remediation
+ * is `gazetta publish <target>` before retrying `gazetta deploy`.
+ */
+export class DeployContentError extends DeployError {
+    constructor(message, adapter) {
+        super(message, adapter);
+        this.name = 'DeployContentError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/deploy/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/deploy/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpB,OAAO,CAAQ;IAE/B,YAAY,OAAe,EAAE,OAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,aAAa,CAAA;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACxB,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,iBAAkB,SAAQ,WAAW;IAChD,YAAY,OAAe,EAAE,OAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;IACjC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,eAAgB,SAAQ,WAAW;IAC9C,YAAY,OAAe,EAAE,OAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;IAC/B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,oBAAqB,SAAQ,WAAW;IACnD,YAAY,OAAe,EAAE,OAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;IACpC,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IACjD,YAAY,OAAe,EAAE,OAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IAClC,CAAC;CACF"}

package/dist/deploy/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Deploy barrel. Cut 1 ships the type-only foundation; subsequent
+ * cuts add the validators (Cut 2), `cloudflareWorkersDeploy()`
+ * factory + CLI refactor (Cut 3), and docs (Cut 4).
+ */
+export type { DeployAdapter, DeployContext, DeployLogger, DeployResult, ValidateContext, WorkerCapableDeployAdapter, WorkerRuntimeConfig, } from './types.js';
+export { DeployAuthError, DeployConfigError, DeployContentError, DeployError, DeployTransportError, } from './errors.js';
+export { cloudflareWorkersDeploy, extractDeployUrl, renderWorkerEntry, renderWranglerToml, type CloudflareWorkersDeployOptions, } from './cloudflare-workers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/deploy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/deploy/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,oBAAoB,GACrB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,8BAA8B,GACpC,MAAM,yBAAyB,CAAA"}

package/dist/deploy/index.js

@@ -0,0 +1,3 @@
+export { DeployAuthError, DeployConfigError, DeployContentError, DeployError, DeployTransportError, } from './errors.js';
+export { cloudflareWorkersDeploy, extractDeployUrl, renderWorkerEntry, renderWranglerToml, } from './cloudflare-workers.js';
+//# sourceMappingURL=index.js.map

package/dist/deploy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/deploy/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,oBAAoB,GACrB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,GAEnB,MAAM,yBAAyB,CAAA"}

package/dist/deploy/types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Type contract for the DeployAdapter Pattern 1 Provider surface.
+ *
+ * Cut 1 of the deploy contract — the interface, capability extension,
+ * and supporting types. Subsequent cuts add validators (Cut 2), the
+ * first real adapter (Cut 3 — `cloudflareWorkersDeploy`), and docs
+ * (Cut 4). Per ADR-0008, operators wire adapters via factory calls
+ * returning a constructed `DeployAdapter`; the field type IS the
+ * runtime interface.
+ *
+ * Reference: `.claude/rules/design-deploy.md` "The contract" section.
+ *
+ * Note: `supports: readonly TargetType[]` is forward-compatible with
+ * `design-rendering.md` Q1's three-target-type taxonomy (`'static' |
+ * 'esi' | 'dynamic'`). Today's `TargetType` is `'static' | 'dynamic'`;
+ * Cut 1 of design-rendering.md widens it to include `'esi'`. Adapters
+ * declaring `supports: ['static'] as const` today continue compiling
+ * after that widening.
+ */
+import type { StorageProvider, TargetConfig, TargetType } from '../types.js';
+import type { Issue } from '../validation/types.js';
+/**
+ * The deploy adapter contract. One implementation per platform.
+ *
+ * - `name` — stable identifier for diagnostics, logs, validation
+ *   messages. Kebab-case matching the `module:` convention in
+ *   design-logging.md (e.g., `'cloudflare-workers'`, `'github-pages'`).
+ *   Plugin adapters use their package name (`'@example/custom-deploy'`).
+ * - `supports` — which target types this adapter supports. The
+ *   `deploy-target-type-supported` validator (Cut 2) enforces
+ *   compatibility against `target.type`.
+ * - `execute(ctx)` — run the deploy. Throws `DeployError` variants on
+ *   failure; returns `DeployResult` on success.
+ * - `validate?(ctx)` — optional pre-flight validation for cross-field
+ *   invariants beyond target-type compatibility (e.g., "Cloudflare
+ *   Workers requires bucket binding"). Returns the standard `Issue[]`
+ *   shape from design-validation.md; runs at `cli` + `pre-publish`
+ *   stages of the validation framework.
+ */
+export interface DeployAdapter {
+    readonly name: string;
+    readonly supports: readonly TargetType[];
+    execute(ctx: DeployContext): Promise<DeployResult>;
+    validate?(ctx: ValidateContext): Issue[];
+}
+/**
+ * Capability extension for adapters that bundle worker code
+ * (Cloudflare Workers, Cloudflare Pages + Functions, Vercel Edge,
+ * Netlify Edge, Deno Deploy). `gazetta build` detects this capability
+ * via `'workerRuntimeConfig' in target.deploy` and reads the runtime
+ * config at build time.
+ *
+ * Static-only adapters (GitHub Pages, S3 static, Netlify static,
+ * CF Pages plain-static, Azure Blob static) do NOT implement this
+ * interface — their `target.deploy` value satisfies just
+ * `DeployAdapter`.
+ *
+ * Per Q1 of the design grilling: the capability split keeps
+ * worker-bundling concerns out of the base contract; same pattern as
+ * `BinaryCapableStorageProvider` in design-media-implementation.md.
+ */
+export interface WorkerCapableDeployAdapter extends DeployAdapter {
+    /**
+     * Returns the worker runtime config that `gazetta build` needs to
+     * generate the worker code (R2 bucket binding name, route patterns,
+     * KV bindings, etc.). Called at build time, not at execute time.
+     */
+    workerRuntimeConfig(): WorkerRuntimeConfig;
+}
+/**
+ * Runtime metadata for the worker code `gazetta build` generates.
+ *
+ * - `bucketBinding` — name the worker code uses to access storage
+ *   (e.g., `'SITE_BUCKET'` for the R2 binding). Adapter decides;
+ *   wrangler.toml / equivalent platform config picks it up.
+ * - `routes` — optional route patterns the worker should handle.
+ *   When unset, the adapter relies on platform defaults (e.g.,
+ *   Cloudflare Workers' `workers_dev = true` route).
+ * - `bindings` — adapter-specific extras (Cloudflare KV / D1 /
+ *   Queues, Vercel Edge Config, etc.). Opaque to `gazetta build`;
+ *   the adapter consumes its own structure.
+ */
+export interface WorkerRuntimeConfig {
+    readonly bucketBinding: string;
+    readonly routes?: readonly {
+        pattern: string;
+        zone?: string;
+    }[];
+    readonly bindings?: Record<string, unknown>;
+}
+/**
+ * Context passed to `DeployAdapter.execute()`. Carries everything the
+ * adapter needs to deploy without reading from globals.
+ *
+ * - `target` / `targetName` — the resolved target being deployed.
+ * - `outputDir` — path to pre-rendered output (static + esi targets).
+ *   Adapters that need bytes read from this path; adapters that don't
+ *   (worker-only deploys to platforms reading from external storage
+ *   at request time) ignore it.
+ * - `storage` — the target's `StorageProvider`. Adapters that read
+ *   content during deploy use this; adapters that don't ignore it.
+ *   Per Q4 lock, the CLI doesn't gate on whether storage has been
+ *   published; adapters that need published content surface a
+ *   `DeployContentError` at execute time when missing.
+ * - `env` — `process.env` passthrough. Adapters read platform-specific
+ *   env vars (CLOUDFLARE_API_TOKEN, VERCEL_TOKEN, etc.) per their own
+ *   documentation. Per Q7 lock: adapter-namespaced env vars matching
+ *   platform SDK conventions.
+ * - `logger` — module-scoped logger per design-logging.md. Adapter
+ *   uses `logger.info({...}, 'message')` for operational events.
+ * - `signal` — cancellation signal for long-running deploys. Adapters
+ *   honor it best-effort; not all platform CLIs support mid-deploy
+ *   cancellation.
+ */
+export interface DeployContext {
+    readonly target: TargetConfig;
+    readonly targetName: string;
+    readonly outputDir: string;
+    readonly storage: StorageProvider;
+    readonly env: Record<string, string | undefined>;
+    readonly logger: DeployLogger;
+    readonly signal: AbortSignal;
+}
+/**
+ * Context passed to `DeployAdapter.validate?()`. Narrower than
+ * `DeployContext` because pre-flight validation is a pure function
+ * over config — no I/O, no env, no cancellation.
+ */
+export interface ValidateContext {
+    readonly target: TargetConfig;
+    readonly targetName: string;
+}
+/**
+ * Result returned by `DeployAdapter.execute()` on success.
+ *
+ * - `url` — deployed URL when known. Some platforms surface one
+ *   (Wrangler returns `https://workers-name.workers.dev` after
+ *   deploy); others don't until DNS propagates. Optional.
+ * - `details` — adapter-specific extras (Cloudflare worker version
+ *   ID, Netlify deploy ID, etc.). Surfaced in CLI output for operator
+ *   inspection. Opaque structure.
+ */
+export interface DeployResult {
+    readonly url?: string;
+    readonly details?: Record<string, unknown>;
+}
+/**
+ * Minimal logger interface scoped to a deploy adapter. Mirrors the
+ * shape from design-logging.md (and `HookLogger` in hooks/types.ts).
+ * Concrete logger implementation lives in the logging foundation
+ * (Tier 3); v1 deploy dispatch supplies a no-op logger or pino child
+ * as available.
+ *
+ * No `trace` level — deploy is operator-tier, info-and-up sufficient.
+ */
+export interface DeployLogger {
+    debug(obj: object | string, msg?: string): void;
+    info(obj: object | string, msg?: string): void;
+    warn(obj: object | string, msg?: string): void;
+    error(obj: object | string, msg?: string): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/deploy/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/deploy/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAEnD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAA;IACxC,OAAO,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAClD,QAAQ,CAAC,CAAC,GAAG,EAAE,eAAe,GAAG,KAAK,EAAE,CAAA;CACzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,0BAA2B,SAAQ,aAAa;IAC/D;;;;OAIG;IACH,mBAAmB,IAAI,mBAAmB,CAAA;CAC3C;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IAChD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC3C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAChD"}

package/dist/deploy/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/deploy/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/deploy/types.ts"],"names":[],"mappings":""}

package/dist/editor/AssetEmbeddedWidget.d.ts

@@ -0,0 +1,3 @@
+import type { WidgetProps } from '@rjsf/utils';
+export declare function AssetEmbeddedWidget(props: WidgetProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=AssetEmbeddedWidget.d.ts.map

package/dist/editor/AssetEmbeddedWidget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssetEmbeddedWidget.d.ts","sourceRoot":"","sources":["../../src/editor/AssetEmbeddedWidget.tsx"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAqC9C,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,2CAuFrD"}

package/dist/editor/AssetEmbeddedWidget.js

@@ -0,0 +1,146 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * React rjsf widget for an embedded-asset schema field.
+ *
+ * Renders the current selection (thumbnail + name) or an empty state, with
+ * a "Change" button that calls a picker callback injected via the form
+ * context. The callback's body is the admin's `openAssetPicker` (which
+ * uses Pinia internally) — this widget depends on the abstraction, not
+ * the implementation.
+ *
+ * Dependency Inversion:
+ * - Widget depends on `formContext.onPickAsset`, a Promise-returning fn
+ * - The gazetta editor package knows nothing about how the picker is
+ *   actually implemented (Vue, React, fullscreen, modal — anything goes)
+ * - Admin wires its own implementation when it calls `createEditorMount`
+ * - Cross-workspace import boundary is respected (no `apps/admin` imports
+ *   from the `packages/gazetta` package)
+ *
+ * Asset summary fetch:
+ * - On mount (and whenever `_asset` changes) the widget fetches the
+ *   single-asset summary to render a thumbnail. Missing assets fall back
+ *   to the empty state — graceful degradation matches the design doc's
+ *   resolver principle.
+ */
+import React from 'react';
+function buildThumbnailUrl(summary) {
+    const ext = extFromMime(summary.mime);
+    if (!ext)
+        return null;
+    return `/assets/${summary.name}-${summary.hash}.${ext}`;
+}
+function extFromMime(mime) {
+    switch (mime) {
+        case 'image/jpeg':
+            return 'jpg';
+        case 'image/png':
+            return 'png';
+        default:
+            return null;
+    }
+}
+export function AssetEmbeddedWidget(props) {
+    const value = (props.value ?? {});
+    const assetName = value._asset ?? null;
+    const [summary, setSummary] = React.useState(null);
+    const [loadError, setLoadError] = React.useState(null);
+    // Fetch the current selection's summary for thumbnail + alt. Refetches
+    // when the selected name changes (e.g., after picker confirms).
+    React.useEffect(() => {
+        if (!assetName) {
+            setSummary(null);
+            setLoadError(null);
+            return;
+        }
+        let cancelled = false;
+        // The widget mounts inside the admin's origin; relative URLs resolve
+        // against the current page (admin SPA served under `/admin/` in prod,
+        // `/` in dev-monorepo). The `/admin/api/...` prefix is added by the
+        // admin's build — at runtime we fetch relative to the document.
+        const base = resolveAdminBase();
+        fetch(`${base}/api/assets/${encodeURIComponent(assetName)}`, {
+            headers: { 'Content-Type': 'application/json' },
+        })
+            .then(async (res) => {
+            if (cancelled)
+                return;
+            if (!res.ok) {
+                setSummary(null);
+                setLoadError(`Asset "${assetName}" could not be loaded`);
+                return;
+            }
+            const data = (await res.json());
+            setSummary(data);
+            setLoadError(null);
+        })
+            .catch(err => {
+            if (!cancelled) {
+                setLoadError(err.message);
+                setSummary(null);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [assetName]);
+    const accept = readAccept(props.schema);
+    const thumbnail = summary ? buildThumbnailUrl(summary) : null;
+    async function onPick() {
+        const onPickAsset = props.formContext?.onPickAsset;
+        if (!onPickAsset) {
+            // Admin didn't wire a picker implementation — nothing we can do.
+            // eslint-disable-next-line no-console
+            console.warn('[asset-widget] No onPickAsset callback provided in formContext');
+            return;
+        }
+        const picked = await onPickAsset({
+            accept,
+            currentAssetName: assetName ?? null,
+        });
+        if (!picked)
+            return;
+        // Preserve per-reference overrides when the author re-picks.
+        props.onChange({ ...value, _asset: picked._asset });
+    }
+    return (_jsxs("div", { className: "gz-asset-widget", children: [_jsx("div", { className: "gz-asset-widget-preview", children: thumbnail ? (_jsx("img", { src: thumbnail, alt: summary?.alt ?? '' })) : loadError ? (_jsx("div", { className: "gz-asset-widget-error", children: loadError })) : assetName ? (_jsx("div", { className: "gz-asset-widget-empty", children: "Loading\u2026" })) : (_jsx("div", { className: "gz-asset-widget-empty", children: "No asset selected" })) }), _jsxs("div", { className: "gz-asset-widget-body", children: [_jsx("div", { className: "gz-asset-widget-name", children: assetName ?? '—' }), _jsx("button", { type: "button", className: "gz-asset-widget-pick", "data-testid": "asset-widget-pick", onClick: onPick, children: assetName ? 'Change' : 'Pick' })] })] }));
+}
+/**
+ * Resolve the admin API base URL from the current document. In the
+ * monorepo dev setup the admin is served at `/admin/`; in site-project
+ * dev it's at `/admin/` too; the admin SPA's document is always mounted
+ * under the admin path, so we strip everything after `/admin/` and use
+ * that as the base for `/api/...` calls.
+ *
+ * Keeps the widget free of Vite's `import.meta.env` (which would tie
+ * this package to a Vite build and break its Node-only tsc).
+ */
+function resolveAdminBase() {
+    if (typeof document === 'undefined')
+        return '';
+    const href = document.baseURI;
+    try {
+        const url = new URL(href);
+        // Strip trailing slash; the widget prepends its own `/api/...`.
+        return url.pathname.replace(/\/$/, '');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Read the `accept` filter from the JSON Schema's assetOptions metadata.
+ * Zod's `.meta({ assetOptions })` emits the options as a sibling key on
+ * the field's schema via `z.toJSONSchema()`.
+ */
+function readAccept(schema) {
+    if (!schema || typeof schema !== 'object')
+        return undefined;
+    const opts = schema.assetOptions;
+    if (!opts || typeof opts !== 'object')
+        return undefined;
+    const accept = opts.accept;
+    if (Array.isArray(accept) && accept.every(v => typeof v === 'string'))
+        return accept;
+    return undefined;
+}
+//# sourceMappingURL=AssetEmbeddedWidget.js.map

package/dist/editor/AssetEmbeddedWidget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssetEmbeddedWidget.js","sourceRoot":"","sources":["../../src/editor/AssetEmbeddedWidget.tsx"],"names":[],"mappings":"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"}

package/dist/editor/mount.d.ts

@@ -8,11 +8,22 @@ export interface DefaultEditorFormProps {
     /** Current theme — forwarded to custom field widgets */
     theme?: 'dark' | 'light';
     onChange: (content: Record<string, unknown>) => void;
+    /**
+     * Asset picker callback — invoked by embedded-asset field widgets.
+     * Supplied by the admin; the editor package only depends on the
+     * abstract Promise-returning shape.
+     */
+    onPickAsset?: (options: {
+        accept?: string[];
+        currentAssetName?: string | null;
+    }) => Promise<{
+        _asset: string;
+    } | null>;
 }
 /**
  * The default @rjsf form editor as a React component.
  * Custom editors can embed this: `<DefaultEditorForm schema={schema} content={content} onChange={onChange} />`
  */
-export declare function DefaultEditorForm({ schema: jsonSchema, content, onChange, fieldsBaseUrl, theme, }: DefaultEditorFormProps): import("react/jsx-runtime").JSX.Element;
+export declare function DefaultEditorForm({ schema: jsonSchema, content, onChange, fieldsBaseUrl, theme, onPickAsset, }: DefaultEditorFormProps): import("react/jsx-runtime").JSX.Element;
 export declare function createEditorMount(jsonSchema: object): EditorMount;
 //# sourceMappingURL=mount.d.ts.map

package/dist/editor/mount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../src/editor/mount.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAq+B9C,gDAAgD;AAChD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,qGAAqG;IACrG,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACxB,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CACrD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EAAE,UAAU,EAClB,OAAO,EACP,QAAQ,EACR,aAAa,EACb,KAAK,GACN,EAAE,sBAAsB,2CAoGxB;AAMD,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CA2BjE"}
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../src/editor/mount.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AA8gC9C,gDAAgD;AAChD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,qGAAqG;IACrG,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACxB,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IACpD;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAA;CACvH;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EAAE,UAAU,EAClB,OAAO,EACP,QAAQ,EACR,aAAa,EACb,KAAK,EACL,WAAW,GACZ,EAAE,sBAAsB,2CAoGxB;AAMD,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CA4BjE"}

package/dist/editor/mount.js

@@ -3,6 +3,7 @@ import React from 'react';
 import { createRoot } from 'react-dom/client';
 import Form from '@rjsf/core';
 import validator from '@rjsf/validator-ajv8';
+import { AssetEmbeddedWidget } from './AssetEmbeddedWidget.js';
 import { DragDropContext, Droppable, Draggable } from '@hello-pangea/dnd';
 import { useEditor, EditorContent } from '@tiptap/react';
 import { BubbleMenu } from '@tiptap/react/menus';
@@ -120,6 +121,27 @@ const STYLES = `
   padding: 2rem; text-align: center; color: var(--color-muted); font-size: 0.75rem;
 }
 
+/* ---- Asset widget (embeddedAsset schema fields) ---- */
+.gz-editor .gz-asset-widget {
+  display: grid; grid-template-columns: 120px 1fr; gap: 0.75rem; align-items: start;
+  padding: 0.5rem; border: 1px solid var(--color-border); border-radius: 6px; background: var(--color-input-bg);
+}
+.gz-editor .gz-asset-widget-preview {
+  aspect-ratio: 1 / 1; border-radius: 4px; overflow: hidden;
+  background: color-mix(in srgb, var(--color-muted) 10%, transparent);
+  display: flex; align-items: center; justify-content: center;
+}
+.gz-editor .gz-asset-widget-preview img { width: 100%; height: 100%; object-fit: cover; }
+.gz-editor .gz-asset-widget-empty { color: var(--color-muted); font-size: 0.6875rem; text-align: center; padding: 0.5rem; }
+.gz-editor .gz-asset-widget-error { color: var(--color-danger-fg, #c04040); font-size: 0.6875rem; text-align: center; padding: 0.5rem; }
+.gz-editor .gz-asset-widget-body { display: flex; flex-direction: column; justify-content: space-between; gap: 0.5rem; min-height: 100%; }
+.gz-editor .gz-asset-widget-name { font-family: ui-monospace, monospace; font-size: 0.8125rem; word-break: break-word; }
+.gz-editor .gz-asset-widget-pick {
+  align-self: flex-start; padding: 0.375rem 0.75rem; font-size: 0.8125rem;
+  background: var(--color-primary); color: white; border: none; border-radius: 4px; cursor: pointer;
+}
+.gz-editor .gz-asset-widget-pick:hover { opacity: 0.9; }
+
 /* ---- Slug ---- */
 .gz-editor .gz-slug-widget input {
   font-family: 'JetBrains Mono', 'Fira Code', monospace; font-size: 0.8125rem; letter-spacing: 0.02em;
@@ -309,7 +331,15 @@ function buildUiSchema(jsonSchema) {
         const format = prop.format;
         const type = prop.type;
         const customField = prop.field;
-        // Custom field — highest priority
+        const assetOptions = prop.assetOptions;
+        // Asset fields — detected by the `assetOptions` metadata that
+        // `embeddedAsset()` attaches via Zod `.meta()`. Rendered with the
+        // asset widget (invokes the picker via formContext.onPickAsset).
+        if (assetOptions) {
+            ui[name] = { 'ui:widget': 'embedded-asset' };
+            continue;
+        }
+        // Custom field — highest priority after asset fields
         if (customField) {
             ui[name] = { 'ui:widget': `custom-field:${customField}` };
             continue;
@@ -630,6 +660,7 @@ const builtinWidgets = {
     slug: SlugWidget,
     code: CodeWidget,
     json: JsonWidget,
+    'embedded-asset': AssetEmbeddedWidget,
 };
 /** Build widgets object including any custom field widgets referenced in the schema */
 function buildWidgets(jsonSchema) {
@@ -656,7 +687,7 @@ const customTemplates = {
  * The default @rjsf form editor as a React component.
  * Custom editors can embed this: `<DefaultEditorForm schema={schema} content={content} onChange={onChange} />`
  */
-export function DefaultEditorForm({ schema: jsonSchema, content, onChange, fieldsBaseUrl, theme, }) {
+export function DefaultEditorForm({ schema: jsonSchema, content, onChange, fieldsBaseUrl, theme, onPickAsset, }) {
     const uiSchema = React.useMemo(() => buildUiSchema(jsonSchema), [jsonSchema]);
     const widgets = React.useMemo(() => buildWidgets(jsonSchema), [jsonSchema]);
     const [formData, setFormData] = React.useState(content);
@@ -725,7 +756,7 @@ export function DefaultEditorForm({ schema: jsonSchema, content, onChange, field
             return updated;
         });
     }, [onChange]);
-    const formContext = React.useMemo(() => ({ reorderArray, fieldsBaseUrl, theme }), [reorderArray, fieldsBaseUrl, theme]);
+    const formContext = React.useMemo(() => ({ reorderArray, fieldsBaseUrl, theme, onPickAsset }), [reorderArray, fieldsBaseUrl, theme, onPickAsset]);
     return (_jsxs(_Fragment, { children: [_jsx("style", { children: STYLES }), _jsx("div", { className: "gz-editor", children: _jsx(Form, { schema: jsonSchema, uiSchema: uiSchema, formData: formData, onChange: handleChange, validator: validator, widgets: widgets, templates: customTemplates, formContext: formContext, liveValidate: false, omitExtraData: true, noHtml5Validate: true, autoComplete: "off" }) })] }));
 }
 // ---------------------------------------------------------------------------
@@ -733,13 +764,13 @@ export function DefaultEditorForm({ schema: jsonSchema, content, onChange, field
 // ---------------------------------------------------------------------------
 export function createEditorMount(jsonSchema) {
     return {
-        mount(el, { content, schema, theme, onChange, fieldsBaseUrl }) {
+        mount(el, { content, schema, theme, onChange, fieldsBaseUrl, onPickAsset }) {
             const existing = roots.get(el);
             if (existing)
                 existing.unmount();
             const root = createRoot(el);
             roots.set(el, root);
-            root.render(_jsx(DefaultEditorForm, { schema: schema ?? jsonSchema, content: content, theme: theme, fieldsBaseUrl: fieldsBaseUrl, onChange: onChange }));
+            root.render(_jsx(DefaultEditorForm, { schema: schema ?? jsonSchema, content: content, theme: theme, fieldsBaseUrl: fieldsBaseUrl, onPickAsset: onPickAsset, onChange: onChange }));
         },
         unmount(el) {
             const root = roots.get(el);