veryfront 0.1.90 → 0.1.91

package/esm/src/sandbox/sandbox.d.ts

@@ -17,6 +17,53 @@ export interface ExecStreamEvent {
     data?: string;
     exitCode?: number;
 }
+/** Status of an async command job. */
+export type CommandJobStatus = "running" | "completed" | "failed" | "canceled";
+/** Heartbeat health status for a command job. */
+export type CommandJobHeartbeatStatus = "disabled" | "healthy" | "degraded";
+/** An async command job running in a sandbox. */
+export interface CommandJob {
+    id: string;
+    status: CommandJobStatus;
+    exitCode: number | null;
+    signal: string | null;
+    startedAt: string;
+    finishedAt: string | null;
+    heartbeatStatus: CommandJobHeartbeatStatus;
+    lastHeartbeatAt: string | null;
+    lastHeartbeatError: string | null;
+    heartbeatFailureCount: number;
+}
+/** A command job with its captured output. */
+export interface CommandJobOutput extends CommandJob {
+    stdout: string;
+    stderr: string;
+    stdoutTruncated: boolean;
+    stderrTruncated: boolean;
+}
+/** A sandbox session summary returned by list. */
+export interface SandboxSession {
+    id: string;
+    shortId: string;
+    endpoint: string;
+    status: string;
+    createdAt: string;
+}
+/** Options for listing sandbox sessions. */
+export interface SandboxListOptions extends SandboxOptions {
+    cursor?: string;
+    limit?: number;
+}
+/** Paginated result of sandbox sessions. */
+export interface SandboxListResult {
+    data: SandboxSession[];
+    pageInfo: {
+        self: string | null;
+        first: null;
+        next: string | null;
+        prev: string | null;
+    };
+}
 /** Client for isolated ephemeral compute environments with command execution and file I/O. */
 export declare class Sandbox {
     private endpoint;
@@ -30,6 +77,8 @@ export declare class Sandbox {
     static create(options?: SandboxOptions): Promise<Sandbox>;
     /** Reconnect to an existing sandbox session. */
     static get(id: string, options?: SandboxOptions): Promise<Sandbox>;
+    /** List sandbox sessions with optional pagination. */
+    static list(options?: SandboxListOptions): Promise<SandboxListResult>;
     private static waitForReady;
     /** Execute a bash command in the sandbox and return buffered result. */
     executeCommand(command: string): Promise<ExecResult>;
@@ -42,6 +91,15 @@ export declare class Sandbox {
         path: string;
         content: string;
     }>): Promise<void>;
+    /** Start an async command job in the sandbox. */
+    startCommandJob(command: string): Promise<CommandJob>;
+    /** Get the status of an async command job. */
+    getCommandJob(jobId: string): Promise<CommandJob>;
+    /** Get the output of an async command job. */
+    getCommandJobOutput(jobId: string): Promise<CommandJobOutput>;
+    /** Cancel an async command job. */
+    cancelCommandJob(jobId: string): Promise<CommandJob>;
+    private static mapCommandJob;
     /** Send a heartbeat to prevent idle timeout. */
     heartbeat(): Promise<void>;
     /** Close the sandbox session and mark for deletion. */

package/esm/src/sandbox/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/src/sandbox/sandbox.ts"],"names":[],"mappings":"AAqBA,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,8FAA8F;AAC9F,qBAAa,OAAO;IAEhB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,MAAM;IAJhB,OAAO;IAOP,OAAO,CAAC,MAAM,CAAC,aAAa;IAM5B,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAa/B,4EAA4E;WAC/D,MAAM,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BnE,gDAAgD;WACnC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;mBAkBvD,YAAY;IA6BjC,wEAAwE;IAClE,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAsB1D,6DAA6D;IACtD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,eAAe,CAAC;IAyCtE,8CAA8C;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAe7C,4CAA4C;IACtC,UAAU,CACd,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GAC9C,OAAO,CAAC,IAAI,CAAC;IAiBhB,gDAAgD;IAC1C,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAOhC,uDAAuD;IACjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B,0BAA0B;IAC1B,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,oCAAoC;IACpC,IAAI,GAAG,IAAI,MAAM,CAEhB;CACF"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/src/sandbox/sandbox.ts"],"names":[],"mappings":"AAqBA,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,sCAAsC;AACtC,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE/E,iDAAiD;AACjD,MAAM,MAAM,yBAAyB,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC;AAE5E,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,eAAe,EAAE,yBAAyB,CAAC;IAC3C,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,8CAA8C;AAC9C,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,OAAO,CAAC;IACzB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,4CAA4C;AAC5C,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,KAAK,EAAE,IAAI,CAAC;QACZ,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;KACrB,CAAC;CACH;AAED,8FAA8F;AAC9F,qBAAa,OAAO;IAEhB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,MAAM;IAJhB,OAAO;IAOP,OAAO,CAAC,MAAM,CAAC,aAAa;IAM5B,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAa/B,4EAA4E;WAC/D,MAAM,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BnE,gDAAgD;WACnC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAkB5E,sDAAsD;WACzC,IAAI,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;mBAwC1D,YAAY;IA6BjC,wEAAwE;IAClE,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAsB1D,6DAA6D;IACtD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,eAAe,CAAC;IAyCtE,8CAA8C;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAe7C,4CAA4C;IACtC,UAAU,CACd,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GAC9C,OAAO,CAAC,IAAI,CAAC;IAiBhB,iDAAiD;IAC3C,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAmB3D,8CAA8C;IACxC,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAcvD,8CAA8C;IACxC,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqBnE,mCAAmC;IAC7B,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAe1D,OAAO,CAAC,MAAM,CAAC,aAAa;IAe5B,gDAAgD;IAC1C,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAOhC,uDAAuD;IACjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B,0BAA0B;IAC1B,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,oCAAoC;IACpC,IAAI,GAAG,IAAI,MAAM,CAEhB;CACF"}

package/esm/src/sandbox/sandbox.js

@@ -74,6 +74,42 @@ export class Sandbox {
         const { endpoint } = await res.json();
         return new Sandbox(endpoint, id, authToken, apiUrl);
     }
+    /** List sandbox sessions with optional pagination. */
+    static async list(options = {}) {
+        const apiUrl = Sandbox.resolveApiUrl(options);
+        const authToken = Sandbox.resolveAuthToken(options);
+        const params = new URLSearchParams();
+        if (options.cursor)
+            params.set("cursor", options.cursor);
+        if (options.limit !== undefined)
+            params.set("limit", String(options.limit));
+        const query = params.toString();
+        const url = `${apiUrl}/sandbox-sessions${query ? `?${query}` : ""}`;
+        const res = await dntShim.fetch(url, {
+            headers: { Authorization: `Bearer ${authToken}` },
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `Failed to list sandboxes: ${res.status} ${await res.text()}`,
+            });
+        }
+        const json = await res.json();
+        return {
+            data: json.data.map((s) => ({
+                id: s.id,
+                shortId: s.short_id,
+                endpoint: s.endpoint,
+                status: s.status,
+                createdAt: s.created_at,
+            })),
+            pageInfo: {
+                self: json.page_info?.self ?? null,
+                first: null,
+                next: json.page_info?.next ?? null,
+                prev: json.page_info?.prev ?? null,
+            },
+        };
+    }
     static async waitForReady(apiUrl, id, authToken, maxWaitMs = 60_000, pollIntervalMs = 2_000) {
         const start = Date.now();
         while (Date.now() - start < maxWaitMs) {
@@ -177,6 +213,81 @@ export class Sandbox {
             });
         }
     }
+    /** Start an async command job in the sandbox. */
+    async startCommandJob(command) {
+        const res = await dntShim.fetch(`${this.endpoint}/exec/jobs`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.authToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ command }),
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `Start command job failed: ${res.status} ${await res.text()}`,
+            });
+        }
+        return Sandbox.mapCommandJob(await res.json());
+    }
+    /** Get the status of an async command job. */
+    async getCommandJob(jobId) {
+        const res = await dntShim.fetch(`${this.endpoint}/exec/jobs/${jobId}`, {
+            headers: { Authorization: `Bearer ${this.authToken}` },
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `Get command job failed: ${res.status} ${await res.text()}`,
+            });
+        }
+        return Sandbox.mapCommandJob(await res.json());
+    }
+    /** Get the output of an async command job. */
+    async getCommandJobOutput(jobId) {
+        const res = await dntShim.fetch(`${this.endpoint}/exec/jobs/${jobId}/output`, {
+            headers: { Authorization: `Bearer ${this.authToken}` },
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `Get command job output failed: ${res.status} ${await res.text()}`,
+            });
+        }
+        const json = await res.json();
+        return {
+            ...Sandbox.mapCommandJob(json),
+            stdout: json.stdout,
+            stderr: json.stderr,
+            stdoutTruncated: json.stdout_truncated,
+            stderrTruncated: json.stderr_truncated,
+        };
+    }
+    /** Cancel an async command job. */
+    async cancelCommandJob(jobId) {
+        const res = await dntShim.fetch(`${this.endpoint}/exec/jobs/${jobId}/cancel`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${this.authToken}` },
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `Cancel command job failed: ${res.status} ${await res.text()}`,
+            });
+        }
+        return Sandbox.mapCommandJob(await res.json());
+    }
+    static mapCommandJob(json) {
+        return {
+            id: json.id,
+            status: json.status,
+            exitCode: json.exit_code,
+            signal: json.signal,
+            startedAt: json.started_at,
+            finishedAt: json.finished_at,
+            heartbeatStatus: json.heartbeat_status,
+            lastHeartbeatAt: json.last_heartbeat_at,
+            lastHeartbeatError: json.last_heartbeat_error,
+            heartbeatFailureCount: json.heartbeat_failure_count,
+        };
+    }
     /** Send a heartbeat to prevent idle timeout. */
     async heartbeat() {
         await dntShim.fetch(`${this.apiUrl}/sandbox-sessions/${this.sessionId}/heartbeat`, {

package/esm/src/server/handlers/dev/styles-css.handler.d.ts

@@ -13,6 +13,11 @@ export declare class StylesCSSHandler extends BaseHandler {
     private loadStylesheet;
     private generateStylesheet;
     private getContentContext;
+    private getVeryfrontApiClient;
     private createPreparedCSSContext;
+    private resolveStyleArtifactSelector;
+    private tryResolveRemotePreparedCSS;
+    private getPreparedCSSByHash;
+    private registerPreparedCSSArtifact;
 }
 //# sourceMappingURL=styles-css.handler.d.ts.map

package/esm/src/server/handlers/dev/styles-css.handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"styles-css.handler.d.ts","sourceRoot":"","sources":["../../../../../src/src/server/handlers/dev/styles-css.handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,OAAO,MAAM,2BAA2B,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAoBnG,qBAAa,gBAAiB,SAAQ,WAAW;IAC/C,QAAQ,EAAE,eAAe,CAKvB;IAEI,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;YAqIjE,cAAc;IAkB5B,OAAO,CAAC,kBAAkB;IAc1B,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,wBAAwB;CAyBjC"}
+{"version":3,"file":"styles-css.handler.d.ts","sourceRoot":"","sources":["../../../../../src/src/server/handlers/dev/styles-css.handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,OAAO,MAAM,2BAA2B,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AA+BnG,qBAAa,gBAAiB,SAAQ,WAAW;IAC/C,QAAQ,EAAE,eAAe,CAKvB;IAEI,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;YAiKjE,cAAc;IAkB5B,OAAO,CAAC,kBAAkB;IAc1B,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,wBAAwB;IA0BhC,OAAO,CAAC,4BAA4B;YA2CtB,2BAA2B;YAiD3B,oBAAoB;YASpB,2BAA2B;CA0B1C"}

package/esm/src/server/handlers/dev/styles-css.handler.js

@@ -1,7 +1,7 @@
 import { BaseHandler } from "../response/base.js";
 import { HTTP_OK, PRIORITY_HIGH_DEV } from "../../../utils/constants/index.js";
 import { joinPath } from "../../../utils/path-utils.js";
-import { formatCSSError, getProjectCSS } from "../../../html/styles-builder/tailwind-compiler.js";
+import { formatCSSError, getCSSByHashAsync, getProjectCSS, regenerateCSSByHash, } from "../../../html/styles-builder/tailwind-compiler.js";
 import { DEFAULT_STYLESHEET } from "../../../html/styles-builder/css-hash-cache.js";
 import { resolveStyleContentVersion } from "../../../html/styles-builder/content-version.js";
 import { createPreparedProjectCSSContext, storePreparedProjectCSS, tryGetPreparedProjectCSS, } from "../../../html/styles-builder/prepared-project-css-cache.js";
@@ -48,6 +48,15 @@ export class StylesCSSHandler extends BaseHandler {
                         return this.respond(responseBuilder.withContentType("text/css; charset=utf-8", prepared.css, HTTP_OK));
                     }
                 }
+                const remotePrepared = await this.tryResolveRemotePreparedCSS(ctx, projectScope, styleProfile.hash, contentContext, preparedContext);
+                if (remotePrepared) {
+                    logger.debug("Prepared CSS resolved via style artifact metadata", {
+                        projectScope,
+                        styleProfileHash: styleProfile.hash,
+                        cssHash: remotePrepared.hash,
+                    });
+                    return this.respond(responseBuilder.withContentType("text/css; charset=utf-8", remotePrepared.css, HTTP_OK));
+                }
                 let candidates;
                 try {
                     candidates = await extractProjectCandidates(ctx);
@@ -112,6 +121,9 @@ body::before {
                         hash: result.hash,
                     });
                 }
+                if ("hash" in result) {
+                    await this.registerPreparedCSSArtifact(ctx, styleProfile.hash, contentContext, result.hash);
+                }
                 return this.respond(responseBuilder.withContentType("text/css; charset=utf-8", result.css, HTTP_OK));
             });
         }
@@ -158,6 +170,13 @@ body::before {
         const fsAdapter = wrappedFs.getUnderlyingAdapter();
         return typeof fsAdapter.getContentContext === "function" ? fsAdapter.getContentContext() : null;
     }
+    getVeryfrontApiClient(ctx) {
+        const wrappedFs = ctx.adapter.fs;
+        if (typeof wrappedFs.getUnderlyingAdapter !== "function")
+            return null;
+        const fsAdapter = wrappedFs.getUnderlyingAdapter();
+        return typeof fsAdapter.getClient === "function" ? fsAdapter.getClient() : null;
+    }
     createPreparedCSSContext(projectScope, rawCss, styleProfileHash, contentContext, ctx) {
         if (!projectScope)
             return undefined;
@@ -171,4 +190,105 @@ body::before {
             buildMode: "production",
         });
     }
+    resolveStyleArtifactSelector(contentContext, ctx) {
+        if (contentContext?.sourceType === "branch" && contentContext.branch) {
+            return {
+                branch: contentContext.branch,
+            };
+        }
+        if (contentContext?.sourceType === "environment" && contentContext.environmentName) {
+            return {
+                environmentName: contentContext.environmentName,
+            };
+        }
+        if (contentContext?.sourceType === "release" && contentContext.releaseId) {
+            return {
+                releaseId: contentContext.releaseId,
+            };
+        }
+        if (ctx.parsedDomain?.branch) {
+            return {
+                branch: ctx.parsedDomain.branch,
+            };
+        }
+        if (ctx.environmentName) {
+            return {
+                environmentName: ctx.environmentName,
+            };
+        }
+        if (ctx.releaseId) {
+            return {
+                releaseId: ctx.releaseId,
+            };
+        }
+        return null;
+    }
+    async tryResolveRemotePreparedCSS(ctx, projectScope, styleProfileHash, contentContext, preparedContext) {
+        if (!projectScope)
+            return undefined;
+        const selector = this.resolveStyleArtifactSelector(contentContext, ctx);
+        if (!selector)
+            return undefined;
+        const client = this.getVeryfrontApiClient(ctx);
+        if (!client)
+            return undefined;
+        try {
+            const resolved = await client.resolveStyleArtifact({
+                ...selector,
+                styleProfileHash,
+            });
+            if (resolved.status !== "ready" || !resolved.artifactHash) {
+                return undefined;
+            }
+            const css = await this.getPreparedCSSByHash(resolved.artifactHash, projectScope);
+            if (!css)
+                return undefined;
+            if (preparedContext) {
+                await storePreparedProjectCSS(preparedContext, {
+                    css,
+                    hash: resolved.artifactHash,
+                });
+            }
+            return {
+                css,
+                hash: resolved.artifactHash,
+            };
+        }
+        catch (error) {
+            logger.debug("Failed to resolve prepared CSS via style artifact metadata", {
+                projectScope,
+                styleProfileHash,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return undefined;
+        }
+    }
+    async getPreparedCSSByHash(cssHash, projectScope) {
+        const cached = await getCSSByHashAsync(cssHash);
+        if (cached)
+            return cached;
+        return regenerateCSSByHash(cssHash, projectScope);
+    }
+    async registerPreparedCSSArtifact(ctx, styleProfileHash, contentContext, cssHash) {
+        const selector = this.resolveStyleArtifactSelector(contentContext, ctx);
+        if (!selector)
+            return;
+        const client = this.getVeryfrontApiClient(ctx);
+        if (!client)
+            return;
+        try {
+            await client.upsertStyleArtifact({
+                ...selector,
+                styleProfileHash,
+                artifactHash: cssHash,
+            });
+        }
+        catch (error) {
+            logger.debug("Failed to register prepared CSS artifact", {
+                cssHash,
+                styleProfileHash,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veryfront",
-  "version": "0.1.90",
+  "version": "0.1.91",
   "description": "The simplest way to build AI-powered apps",
   "keywords": [
     "react",

package/src/deno.js

@@ -1,6 +1,6 @@
 export default {
   "name": "veryfront",
-  "version": "0.1.90",
+  "version": "0.1.91",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "exclude": [

package/src/src/platform/adapters/veryfront-api-client/client.ts

@@ -3,7 +3,10 @@ import {
   type FileDetail,
   type FileListResult,
   type ListFilesOptions,
+  type ProjectStyleArtifactResolution,
+  type ResolveStyleArtifactInput,
   type TokenProvider,
+  type UpsertStyleArtifactInput,
   VeryfrontAPIOperations,
 } from "./operations.js";
 import { API_CLIENT_ERROR, type VeryfrontAPIConfig } from "./types.js";
@@ -340,6 +343,20 @@ export class VeryfrontApiClient {
     return this.operations.lookupProjectByDomain(domain);
   }
 
+  resolveStyleArtifact(
+    input: ResolveStyleArtifactInput,
+    projectRef = this.getProjectSlug()!,
+  ): Promise<ProjectStyleArtifactResolution> {
+    return this.operations.resolveStyleArtifact(projectRef, input);
+  }
+
+  upsertStyleArtifact(
+    input: UpsertStyleArtifactInput,
+    projectRef = this.getProjectSlug()!,
+  ): Promise<ProjectStyleArtifactResolution> {
+    return this.operations.upsertStyleArtifact(projectRef, input);
+  }
+
   // =============================================================================
   // Adapter Convenience Methods
   // =============================================================================

package/src/src/platform/adapters/veryfront-api-client/index.ts

@@ -9,6 +9,10 @@ export {
   type FileDetail,
   type FileListResult,
   type ListFilesOptions,
+  type ProjectStyleArtifactResolution,
+  type ResolveStyleArtifactInput,
+  type StyleArtifactSelector,
+  type UpsertStyleArtifactInput,
   VeryfrontAPIOperations,
 } from "./operations.js";
 export { type RequestOptions, requestWithRetry, type RetryConfig } from "./retry-handler.js";
@@ -39,4 +43,6 @@ export {
   ProjectSchema,
   ReleaseFileDetailSchema,
   ReleaseFileListItemSchema,
+  type StyleArtifactResolveResponse,
+  StyleArtifactResolveResponseSchema,
 } from "./schemas/index.js";

package/src/src/platform/adapters/veryfront-api-client/operations.ts

@@ -1,6 +1,6 @@
 import { logger as baseLogger } from "../../../utils/index.js";
 import { z } from "zod";
-import { requestWithRetry, type RetryConfig } from "./retry-handler.js";
+import { type RequestOptions, requestWithRetry, type RetryConfig } from "./retry-handler.js";
 import { API_CLIENT_ERROR } from "./types.js";
 import {
   BranchFileDetailSchema,
@@ -15,6 +15,7 @@ import {
   type ProjectFile,
   ProjectSchema,
   ReleaseFileDetailSchema,
+  StyleArtifactResolveResponseSchema,
 } from "./schemas/index.js";
 import { withSpan } from "../../../observability/tracing/otlp-setup.js";
 import { SpanNames } from "../../../observability/tracing/span-names.js";
@@ -53,6 +54,32 @@ export interface FileDetail {
   release_version?: string | null;
 }
 
+export interface StyleArtifactSelector {
+  branch?: string;
+  environmentName?: string;
+  releaseId?: string;
+}
+
+export interface ResolveStyleArtifactInput extends StyleArtifactSelector {
+  styleProfileHash: string;
+}
+
+export interface UpsertStyleArtifactInput extends ResolveStyleArtifactInput {
+  artifactHash: string;
+  assetPath?: string;
+  contentType?: string;
+  etag?: string;
+}
+
+export interface ProjectStyleArtifactResolution {
+  status: "ready" | "missing";
+  artifactHash?: string;
+  assetPath?: string;
+  etag?: string;
+  contentType?: string;
+  updatedAt?: string;
+}
+
 function buildListParams(options: ListFilesOptions): URLSearchParams {
   const { cursor, limit = DEFAULT_PAGE_LIMIT, pattern, sortBy = "updated_at", sortOrder = "desc" } =
     options;
@@ -81,6 +108,30 @@ function mapProjectFile<T extends ProjectFile>(file: T): ProjectFile {
   };
 }
 
+function buildStyleArtifactParams(input: ResolveStyleArtifactInput): URLSearchParams {
+  const params = new URLSearchParams({
+    style_profile_hash: input.styleProfileHash,
+  });
+
+  if (input.branch) params.set("branch", input.branch);
+  if (input.environmentName) params.set("environment_name", input.environmentName);
+  if (input.releaseId) params.set("release_id", input.releaseId);
+
+  return params;
+}
+
+function mapStyleArtifactResolution(raw: unknown): ProjectStyleArtifactResolution {
+  const response = StyleArtifactResolveResponseSchema.parse(raw);
+  return {
+    status: response.status,
+    artifactHash: response.artifact_hash,
+    assetPath: response.asset_path,
+    etag: response.etag,
+    contentType: response.content_type,
+    updatedAt: response.updated_at,
+  };
+}
+
 async function listAllFiles(
   list: (cursor?: string) => Promise<FileListResult>,
 ): Promise<ProjectFile[]> {
@@ -423,11 +474,67 @@ export class VeryfrontAPIOperations {
     );
   }
 
-  private request(endpoint: string): Promise<unknown> {
+  async resolveStyleArtifact(
+    projectRef: string,
+    input: ResolveStyleArtifactInput,
+  ): Promise<ProjectStyleArtifactResolution> {
+    const params = buildStyleArtifactParams(input);
+    const url = `/projects/${encodeURIComponent(projectRef)}/style-artifacts/current?${params}`;
+    logger.debug("resolveStyleArtifact", {
+      projectRef,
+      branch: input.branch,
+      environmentName: input.environmentName,
+      releaseId: input.releaseId,
+      styleProfileHash: input.styleProfileHash,
+    });
+
+    return mapStyleArtifactResolution(await this.request(url));
+  }
+
+  async upsertStyleArtifact(
+    projectRef: string,
+    input: UpsertStyleArtifactInput,
+  ): Promise<ProjectStyleArtifactResolution> {
+    const url = `/projects/${encodeURIComponent(projectRef)}/style-artifacts/current`;
+    logger.debug("upsertStyleArtifact", {
+      projectRef,
+      branch: input.branch,
+      environmentName: input.environmentName,
+      releaseId: input.releaseId,
+      styleProfileHash: input.styleProfileHash,
+      artifactHash: input.artifactHash,
+    });
+
+    return mapStyleArtifactResolution(
+      await this.request(url, {
+        method: "PUT",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          style_profile_hash: input.styleProfileHash,
+          branch: input.branch,
+          environment_name: input.environmentName,
+          release_id: input.releaseId,
+          artifact_hash: input.artifactHash,
+          asset_path: input.assetPath,
+          content_type: input.contentType,
+          etag: input.etag,
+        }),
+      }),
+    );
+  }
+
+  private request(endpoint: string, options: RequestOptions = {}): Promise<unknown> {
     return withSpan(
       SpanNames.API_REQUEST,
       () =>
-        requestWithRetry(`${this.apiBaseUrl}${endpoint}`, this.tokenProvider(), this.retryConfig),
+        requestWithRetry(
+          `${this.apiBaseUrl}${endpoint}`,
+          this.tokenProvider(),
+          this.retryConfig,
+          options,
+        ),
       { "api.endpoint": endpoint, "api.base_url": this.apiBaseUrl },
     );
   }

package/src/src/platform/adapters/veryfront-api-client/schemas/api.schema.ts

@@ -147,6 +147,15 @@ export const LookupDomainResponseSchema = z.object({
   release_id: z.string().uuid().nullable(),
 });
 
+export const StyleArtifactResolveResponseSchema = z.object({
+  status: z.enum(["ready", "missing"]),
+  artifact_hash: z.string().optional(),
+  asset_path: z.string().optional(),
+  etag: z.string().optional(),
+  content_type: z.string().optional(),
+  updated_at: z.string().optional(),
+});
+
 export type Project = z.infer<typeof ProjectSchema>;
 export type ProjectFile = z.infer<typeof ProjectFileSchema>;
 export type PageInfo = z.infer<typeof PageInfoSchema>;
@@ -165,6 +174,7 @@ export type ListReleaseFilesResponse = z.infer<typeof ListReleaseFilesResponseSc
 export type ReleaseFileDetail = z.infer<typeof ReleaseFileDetailSchema>;
 
 export type LookupDomainResponse = z.infer<typeof LookupDomainResponseSchema>;
+export type StyleArtifactResolveResponse = z.infer<typeof StyleArtifactResolveResponseSchema>;
 
 export const API_ENDPOINTS = {
   listProjects: {
@@ -212,4 +222,10 @@ export const API_ENDPOINTS = {
     path: "/projects/{domain}",
     description: "Look up project by custom domain (resolved via project_reference)",
   },
+  resolveStyleArtifact: {
+    method: "GET" as const,
+    path: "/projects/{projectRef}/style-artifacts/current",
+    description:
+      "Resolve metadata for the latest ready style artifact for a branch, environment, or release selector",
+  },
 } as const;

package/src/src/platform/adapters/veryfront-api-client/schemas/index.ts

@@ -35,4 +35,6 @@ export {
   ReleaseFileDetailSchema,
   type ReleaseFileListItem,
   ReleaseFileListItemSchema,
+  type StyleArtifactResolveResponse,
+  StyleArtifactResolveResponseSchema,
 } from "./api.schema.js";

package/src/src/sandbox/index.ts

@@ -19,4 +19,16 @@
 import "../../_dnt.polyfills.js";
 
 
-export { type ExecResult, type ExecStreamEvent, Sandbox, type SandboxOptions } from "./sandbox.js";
+export {
+  type CommandJob,
+  type CommandJobHeartbeatStatus,
+  type CommandJobOutput,
+  type CommandJobStatus,
+  type ExecResult,
+  type ExecStreamEvent,
+  Sandbox,
+  type SandboxListOptions,
+  type SandboxListResult,
+  type SandboxOptions,
+  type SandboxSession,
+} from "./sandbox.js";