@sequenceholdings/artifact-studio 0.2.5 → 0.3.0

package/dist/sdk.js

@@ -1,4 +1,39 @@
+import { storageClient } from '@sequenceholdings/storage';
 export const seq = typeof window !== 'undefined'
     ? window.seq
     : undefined;
 export default seq;
+/** Typed metadata API plus direct browser-host transfers for sandboxed Artifacts. */
+export function createArtifactStorageClient(sdk = seq) {
+    const client = storageClient({ async request(method, path, body) {
+            const response = await sdk.api.fetch(path, { method, body });
+            if (!response.ok)
+                throw new Error(`Storage request failed (${response.status})`);
+            return response.body;
+        } });
+    return { ...client, workspace(id) {
+            const workspace = client.workspace(id);
+            return { ...workspace, uploads: { ...workspace.uploads,
+                    put: (input, file, options) => sdk.storage.upload(id, input, file, options),
+                    resume: (uploadId, file, options) => sdk.storage.resume(id, uploadId, file, options),
+                } };
+        } };
+}
+/** Explicit scope keeps concurrent browser actions isolated. The key is a safe
+ * author label, never a payload or an authentication claim. */
+export function withTraceAction({ key, sdk = seq }, run) {
+    if (!/^[a-zA-Z0-9_.:/-]{1,120}$/.test(key))
+        throw new Error('Use a bounded operation key for tracing');
+    const traceAction = { id: crypto.randomUUID(), key };
+    const fetch = (path, options) => sdk.api.fetch(path, { ...options, traceAction });
+    const request = async (method, path, body) => {
+        const response = await fetch(path, { method, body });
+        if (!response.ok)
+            throw new Error(`API request failed (${response.status})`);
+        return response.body;
+    };
+    return run({ api: { ...sdk.api, fetch,
+            get: (path) => request('GET', path), post: (path, body) => request('POST', path, body),
+            put: (path, body) => request('PUT', path, body), patch: (path, body) => request('PATCH', path, body), delete: (path, body) => request('DELETE', path, body),
+        }, functions: { invoke: (id, params) => sdk.functions.invoke(id, params, traceAction) } });
+}

package/dist/server/broker-contract.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+export declare const artifactServerMethodSchema: z.ZodEnum<{
+    GET: "GET";
+    POST: "POST";
+    DELETE: "DELETE";
+    HEAD: "HEAD";
+    PUT: "PUT";
+    PATCH: "PATCH";
+}>;
+export declare const artifactServerModeSchema: z.ZodDefault<z.ZodEnum<{
+    user: "user";
+    service: "service";
+}>>;
+/** Reject paths that intermediaries can normalize into a different authorization target. */
+export declare function isArtifactApiPath(path: string): boolean;
+/** Atlas validates these operations against current manifest, bindings and principal grants. */
+export declare const artifactServerRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    operation: z.ZodLiteral<"api">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        user: "user";
+        service: "service";
+    }>>;
+    method: z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        DELETE: "DELETE";
+        HEAD: "HEAD";
+        PUT: "PUT";
+        PATCH: "PATCH";
+    }>;
+    path: z.ZodString;
+    body: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"orm">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        user: "user";
+        service: "service";
+    }>>;
+    namespace: z.ZodString;
+    op: z.ZodString;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"storage">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        user: "user";
+        service: "service";
+    }>>;
+    method: z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        DELETE: "DELETE";
+        HEAD: "HEAD";
+        PUT: "PUT";
+        PATCH: "PATCH";
+    }>;
+    path: z.ZodString;
+    body: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"function">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        user: "user";
+        service: "service";
+    }>>;
+    id: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>], "operation">;
+export type ArtifactServerRequest = z.infer<typeof artifactServerRequestSchema>;
+export type ArtifactServerMode = z.infer<typeof artifactServerModeSchema>;

package/dist/server/broker-contract.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+export const artifactServerMethodSchema = z.enum(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE']);
+export const artifactServerModeSchema = z.enum(['user', 'service']).default('user');
+/** Reject paths that intermediaries can normalize into a different authorization target. */
+export function isArtifactApiPath(path) {
+    if (!path.startsWith('/api/') || path.startsWith('//') || /[\\\r\n\u0000#]/.test(path))
+        return false;
+    const pathname = path.split('?')[0];
+    if (/%(?:2e|2f|5c|25)/i.test(pathname) || pathname.includes('//'))
+        return false;
+    if (pathname.split('/').some(part => part === '.' || part === '..'))
+        return false;
+    try {
+        return new URL(path, 'https://artifact.invalid').pathname === pathname;
+    }
+    catch {
+        return false;
+    }
+}
+const path = z.string().min(6).max(8192).refine(isArtifactApiPath, 'Expected a canonical Atlas API path');
+const method = artifactServerMethodSchema;
+const mode = artifactServerModeSchema;
+const id = z.string().min(1).max(255).regex(/^[a-zA-Z0-9_-]+$/);
+/** Atlas validates these operations against current manifest, bindings and principal grants. */
+export const artifactServerRequestSchema = z.discriminatedUnion('operation', [
+    z.object({ operation: z.literal('api'), mode, method, path, body: z.unknown().optional() }).strict(),
+    z.object({ operation: z.literal('orm'), mode, namespace: id, op: z.string().regex(/^sha256:[a-f0-9]{64}$/), variables: z.record(z.string(), z.unknown()).optional() }).strict(),
+    z.object({ operation: z.literal('storage'), mode, method, path: path.refine(value => {
+            const pathname = value.split('?')[0];
+            return pathname === '/api/storage' || pathname.startsWith('/api/storage/');
+        }, 'Expected a Storage API path'), body: z.unknown().optional() }).strict(),
+    z.object({ operation: z.literal('function'), mode, id, params: z.record(z.string(), z.unknown()).optional() }).strict(),
+]);

package/dist/server/client.d.ts

@@ -0,0 +1,67 @@
+import { storageClient } from '@sequenceholdings/storage';
+import { type OperationsManifest, type OperationExecutor } from '@sequenceholdings/orm/client';
+import type { SequenceApiFetchResponse } from '../sdk.js';
+import { type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+import { createArtifactLogger, type ArtifactLogRecord } from './logger.js';
+import { type ArtifactRequestContext } from './request-context.js';
+import { type ArtifactRuntimeConfig, type ArtifactRequestHeaders } from './runtime-config.js';
+export declare class ArtifactServerError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export interface ArtifactServerFetchOptions {
+    method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    signal?: AbortSignal;
+}
+export interface ArtifactServerClient {
+    context: ArtifactRequestContext;
+    mode: ArtifactServerMode;
+    log: ReturnType<typeof createArtifactLogger>;
+    api: ReturnType<typeof createApiClient>;
+    storage: ReturnType<typeof storageClient>;
+    functions: {
+        invoke<TOutput = unknown>(id: string, params?: Record<string, unknown>): Promise<TOutput>;
+    };
+    orm(input: {
+        namespace: string;
+        manifest: OperationsManifest;
+    }): OperationExecutor;
+    asService(): ArtifactServerClient;
+}
+/** One instance per incoming request. Never cache it at module scope. */
+export declare function createArtifactServerClient({ headers, runtime, fetch: fetcher, method, path, logSink }: {
+    headers: ArtifactRequestHeaders;
+    /** Optional explicit platform config; otherwise reads SEQUENCE_ARTIFACT_RUNTIME_FILE. */
+    runtime?: ArtifactRuntimeConfig;
+    fetch?: typeof globalThis.fetch;
+    method?: string;
+    path?: string;
+    logSink?: (record: ArtifactLogRecord) => void;
+}): Promise<ArtifactServerClient>;
+type ClientArguments = {
+    context: ArtifactRequestContext;
+    token: string;
+    getRuntime: () => Promise<ArtifactRuntimeConfig>;
+    fetcher: typeof globalThis.fetch;
+    mode: ArtifactServerMode;
+    logSink?: (record: ArtifactLogRecord) => void;
+};
+type BrokerTransport = ReturnType<typeof createBrokerTransport>;
+declare function createBrokerTransport({ context, token, getRuntime, fetcher }: ClientArguments): (input: ArtifactServerRequest, signal?: AbortSignal) => Promise<Response>;
+declare function createApiClient({ mode, request, json }: {
+    mode: ArtifactServerMode;
+    request: BrokerTransport;
+    json: (operation: ArtifactServerRequest, signal?: AbortSignal) => Promise<unknown>;
+}): {
+    request: (path: string, options?: ArtifactServerFetchOptions) => Promise<Response>;
+    fetch<TBody = unknown>(path: string, options?: ArtifactServerFetchOptions): Promise<SequenceApiFetchResponse<TBody>>;
+    stream(path: string, options?: ArtifactServerFetchOptions): Promise<ReadableStream<Uint8Array<ArrayBuffer>>>;
+    get: <T = unknown>(path: string) => Promise<T>;
+    post: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+    put: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+    patch: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+    delete: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+};
+export {};

package/dist/server/client.js

@@ -0,0 +1,159 @@
+import { StorageApiError, storageClient, storageErrorSchema } from '@sequenceholdings/storage';
+import { OrmOperationError } from '@sequenceholdings/orm/client';
+import { z } from 'zod';
+import { artifactServerRequestSchema } from './broker-contract.js';
+import { createArtifactLogger } from './logger.js';
+import { ARTIFACT_REQUEST_CONTEXT_HEADER, ARTIFACT_RUNTIME_TOKEN_HEADER, ARTIFACT_SERVER_REQUEST_PATH, verifyArtifactRequestContext } from './request-context.js';
+import { artifactRuntimeConfigSchema, readArtifactRuntimeConfig } from './runtime-config.js';
+export class ArtifactServerError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'ArtifactServerError';
+    }
+}
+const graphqlResponseSchema = z.object({
+    data: z.unknown().optional(),
+    errors: z.array(z.object({ message: z.string(), extensions: z.object({ code: z.string().optional() }).passthrough().optional() })).optional(),
+});
+const responseHeaders = ['content-type', 'content-disposition', 'content-length', 'retry-after'];
+const maxBodyBytes = 1024 * 1024;
+/** One instance per incoming request. Never cache it at module scope. */
+export async function createArtifactServerClient({ headers, runtime, fetch: fetcher = globalThis.fetch, method, path, logSink }) {
+    const config = runtime ? artifactRuntimeConfigSchema.parse(runtime) : await readArtifactRuntimeConfig();
+    if (!config)
+        throw new ArtifactServerError(401, 'runtime_not_connected', 'Run seq-studio artifact dev to connect platform services, or use a hosted preview.');
+    const token = headers.get(ARTIFACT_REQUEST_CONTEXT_HEADER);
+    const context = verifyArtifactRequestContext({ token, publicKeys: config.publicKeys, projectId: config.projectId, environment: config.environment, method, path });
+    if (!token || (config.devSessionId && context.devSessionId !== config.devSessionId) ||
+        (config.deploymentId && context.deploymentId !== config.deploymentId))
+        throw new ArtifactServerError(401, 'invalid_runtime_session', 'Artifact request does not belong to this runtime');
+    const getRuntime = async () => {
+        const current = runtime ? config : await readArtifactRuntimeConfig();
+        if (!current || current.projectId !== config.projectId || current.environment !== config.environment || current.atlasUrl !== config.atlasUrl || current.devSessionId !== config.devSessionId || current.deploymentId !== config.deploymentId)
+            throw new ArtifactServerError(401, 'runtime_changed', 'Artifact runtime disconnected or changed; reload the preview');
+        return current;
+    };
+    return buildClient({ context, token, getRuntime, fetcher, mode: 'user', logSink });
+}
+function buildClient(args) {
+    const { context, mode, logSink } = args;
+    const request = createBrokerTransport(args);
+    const json = async (operation, signal) => {
+        const response = await request(operation, signal);
+        if (!response.ok)
+            throw new ArtifactServerError(response.status, 'platform_request_failed', `Atlas rejected the ${operation.operation} request (${response.status})`);
+        return response.status === 204 ? undefined : response.json();
+    };
+    // storageClient retries replay-safe calls on 503 permissions_pending / storage_busy, so Storage
+    // failures keep the envelope's status and code rather than collapsing into platform_request_failed.
+    const storageJson = async (operation) => {
+        const response = await request(operation);
+        if (!response.ok)
+            throw await storageApiError(response);
+        return response.status === 204 ? undefined : response.json();
+    };
+    return {
+        context,
+        mode,
+        log: createArtifactLogger({ context, sink: logSink }),
+        api: createApiClient({ mode, request, json }),
+        storage: storageClient({ request: (method, path, body) => storageJson(artifactServerRequestSchema.parse({ operation: 'storage', mode, method, path, body })) }),
+        functions: {
+            invoke: async (id, params) => {
+                // The caller supplies its application's function output type; Atlas owns runtime validation.
+                return await json(artifactServerRequestSchema.parse({ operation: 'function', mode, id, params }));
+            },
+        },
+        orm: ({ namespace, manifest }) => ({
+            async execute(op, variables = {}) {
+                const hash = op.startsWith('sha256:') ? op : manifest.operations[op]?.hash;
+                if (!hash)
+                    throw new ArtifactServerError(400, 'unknown_orm_operation', 'ORM operation is not in the generated manifest; run seq-studio orm generate');
+                const response = await request(artifactServerRequestSchema.parse({ operation: 'orm', mode, namespace, op: hash, variables }));
+                const parsed = graphqlResponseSchema.safeParse(await response.json().catch(() => null));
+                if (!parsed.success)
+                    throw new OrmOperationError('Malformed Data API response', response.status, 'invalid_response');
+                const first = parsed.data.errors?.[0];
+                if (!response.ok || first)
+                    throw new OrmOperationError(first?.message ?? `Data API request failed (${response.status})`, response.status, first?.extensions?.code ?? null, parsed.data.errors);
+                if (parsed.data.data === undefined || parsed.data.data === null)
+                    throw new OrmOperationError('Malformed Data API response: missing data', response.status, 'invalid_response');
+                // Mirrors the generated ORM executor contract: consumers provide their generated result type.
+                return parsed.data.data;
+            },
+        }),
+        /** Deliberate escalation, still clamped to a separately attached service identity. */
+        asService() {
+            if (!context.serviceAccountId)
+                throw new ArtifactServerError(403, 'service_identity_unavailable', 'No service identity is attached to this runtime');
+            return buildClient({ ...args, mode: 'service' });
+        },
+    };
+}
+/** Mirrors createStorageClient: Storage's `{ error: { code, message } }` envelope survives the broker. */
+async function storageApiError(response) {
+    const envelope = storageErrorSchema.safeParse(await response.json().catch(() => undefined));
+    return new StorageApiError(response.status, envelope.success ? envelope.data.error.code : 'request_failed', envelope.success ? envelope.data.error.message : `Storage request failed (${response.status})`);
+}
+function createBrokerTransport({ context, token, getRuntime, fetcher }) {
+    return async (input, signal) => {
+        if (context.exp <= Math.floor(Date.now() / 1000))
+            throw new ArtifactServerError(401, 'request_context_expired', 'Artifact request context expired; begin a new request');
+        const operation = artifactServerRequestSchema.parse(input);
+        if (operation.mode === 'service' && !context.serviceAccountId)
+            throw new ArtifactServerError(403, 'service_identity_unavailable', 'No service identity is attached to this runtime');
+        const body = JSON.stringify(operation);
+        if (Buffer.byteLength(body, 'utf8') > maxBodyBytes)
+            throw new ArtifactServerError(413, 'request_too_large', 'Server SDK requests are limited to 1 MiB; use Storage uploads for files');
+        const runtime = await getRuntime();
+        return fetcher(`${runtime.atlasUrl}${ARTIFACT_SERVER_REQUEST_PATH}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                [ARTIFACT_RUNTIME_TOKEN_HEADER]: runtime.sessionToken,
+                [ARTIFACT_REQUEST_CONTEXT_HEADER]: token,
+            },
+            body,
+            cache: 'no-store',
+            redirect: 'error',
+            credentials: 'omit',
+            signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(60_000)]) : AbortSignal.timeout(60_000),
+        });
+    };
+}
+function createApiClient({ mode, request, json }) {
+    const operation = (path, options = {}) => artifactServerRequestSchema.parse({ operation: 'api', mode, method: options.method ?? 'GET', path, body: options.body });
+    const fetchResponse = (path, options = {}) => request(operation(path, options), options.signal);
+    const typedJson = async (path, options = {}) => {
+        // Explicit caller result types match the existing browser SDK; the server validates endpoint schemas.
+        return await json(operation(path, options), options.signal);
+    };
+    return {
+        request: fetchResponse,
+        async fetch(path, options = {}) {
+            const response = await fetchResponse(path, options);
+            const contentType = response.headers.get('content-type') ?? '';
+            const body = response.status === 204 ? undefined : contentType.includes('json') ? await response.json() : await response.arrayBuffer();
+            // The caller declares the endpoint's response type, consistent with SequenceApiFetchResponse.
+            return { ok: response.ok, status: response.status, body: body, headers: Object.fromEntries(responseHeaders.flatMap(key => {
+                    const value = response.headers.get(key);
+                    return value === null ? [] : [[key, value]];
+                })) };
+        },
+        async stream(path, options = {}) {
+            const response = await fetchResponse(path, options);
+            if (!response.ok || !response.body)
+                throw new ArtifactServerError(response.status, 'stream_unavailable', 'Atlas did not return a readable response');
+            return response.body;
+        },
+        get: (path) => typedJson(path),
+        post: (path, body) => typedJson(path, { method: 'POST', body }),
+        put: (path, body) => typedJson(path, { method: 'PUT', body }),
+        patch: (path, body) => typedJson(path, { method: 'PATCH', body }),
+        delete: (path, body) => typedJson(path, { method: 'DELETE', body }),
+    };
+}

package/dist/server/logger.d.ts

@@ -0,0 +1,26 @@
+import type { ArtifactRequestContext } from './request-context.js';
+export interface ArtifactLogMetadata {
+    resourceId?: string;
+    operationId?: string;
+    durationMs?: number;
+    count?: number;
+    status?: number;
+    errorCode?: string;
+}
+export interface ArtifactLogRecord extends ArtifactLogMetadata {
+    event: string;
+    level: 'info' | 'warn' | 'error';
+    projectId: string;
+    requestId: string;
+    deploymentId: string | null;
+    devSessionId: string | null;
+}
+/** Structured events deliberately exclude request bodies, URLs, arbitrary messages and error objects. */
+export declare function createArtifactLogger({ context, sink }: {
+    context: ArtifactRequestContext;
+    sink?: (record: ArtifactLogRecord) => void;
+}): {
+    info: (event: string, metadata?: ArtifactLogMetadata) => void;
+    warn: (event: string, metadata?: ArtifactLogMetadata) => void;
+    error: (event: string, metadata?: ArtifactLogMetadata) => void;
+};

package/dist/server/logger.js

@@ -0,0 +1,24 @@
+/** Structured events deliberately exclude request bodies, URLs, arbitrary messages and error objects. */
+export function createArtifactLogger({ context, sink = record => console[record.level](record) }) {
+    const write = (level, event, metadata = {}) => {
+        if (!/^[a-z][a-z0-9_.-]{0,95}$/.test(event))
+            throw new Error('Log event must be a static dot-separated identifier');
+        const safe = {};
+        for (const key of ['durationMs', 'count', 'status']) {
+            const value = metadata[key];
+            if (typeof value === 'number' && Number.isFinite(value))
+                safe[key] = value;
+        }
+        for (const key of ['resourceId', 'operationId', 'errorCode']) {
+            const value = metadata[key];
+            if (typeof value === 'string' && /^[a-zA-Z0-9_.:-]{1,128}$/.test(value))
+                safe[key] = value;
+        }
+        sink({ ...safe, event, level, projectId: context.projectId, requestId: context.requestId, deploymentId: context.deploymentId, devSessionId: context.devSessionId });
+    };
+    return {
+        info: (event, metadata) => write('info', event, metadata),
+        warn: (event, metadata) => write('warn', event, metadata),
+        error: (event, metadata) => write('error', event, metadata),
+    };
+}

package/dist/server/release-forms.d.ts

@@ -0,0 +1,13 @@
+import { TransformStream } from 'node:stream/web';
+/**
+ * Stamp forms with the document's release identity, including GET forms whose
+ * submitter can override the method to POST. The gateway removes the reserved
+ * field from GET query strings before forwarding them to application code.
+ * Only use on decompressed UTF-8 HTML; remove Content-Length and ETag upstream.
+ * Named hidden inputs are skipped by React 19 hydration, preserving RSC markup.
+ * The gateway must reject missing/conflicting markers before admitting mutations.
+ */
+export declare function createReleaseFormTransform({ deploymentId, documentUrl }: {
+    deploymentId: string;
+    documentUrl: string;
+}): TransformStream<Uint8Array, Uint8Array>;

package/dist/server/release-forms.js

@@ -0,0 +1,124 @@
+import { Tokenizer, TokenizerMode } from 'parse5';
+import { TransformStream } from 'node:stream/web';
+const MAX_TOKEN_CHARACTERS = 64 * 1024;
+const PARSE_CHUNK_CHARACTERS = 8 * 1024;
+const rawTextElements = new Set(['style', 'xmp', 'iframe', 'noembed', 'noframes']);
+/**
+ * Use the HTML tokenizer rather than a DOM: streaming RSC documents can contain
+ * arbitrarily long scripts, and serializing a DOM would change application HTML.
+ * The exact parse5 version is pinned because its tokenizer is an internal API.
+ */
+class BoundedHtmlTokenizer extends Tokenizer {
+    completedToken = null;
+    prepareToken(token) {
+        super.prepareToken(token);
+        this.completedToken = token;
+    }
+    _callState(codePoint) {
+        super._callState(codePoint);
+        const pending = this.currentToken;
+        if (pending !== this.completedToken && pending?.location &&
+            this.preprocessor.offset - pending.location.startOffset > MAX_TOKEN_CHARACTERS) {
+            throw new Error('Artifact HTML contains a token exceeding the 64 KiB limit');
+        }
+    }
+    releaseConsumedText() {
+        // There is no DOM consumer. Do not retain a script/text token between writes.
+        this._emitCurrentCharacterToken(null);
+        this.preprocessor.dropParsedChunk();
+    }
+}
+function resolvesToApplication({ action, baseUrl, documentUrl }) {
+    try {
+        // Missing/empty form actions resolve to the document, not its <base> URL.
+        const target = !action ? documentUrl : new URL(action, baseUrl);
+        return target.origin === documentUrl.origin && !target.username && !target.password;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Stamp forms with the document's release identity, including GET forms whose
+ * submitter can override the method to POST. The gateway removes the reserved
+ * field from GET query strings before forwarding them to application code.
+ * Only use on decompressed UTF-8 HTML; remove Content-Length and ETag upstream.
+ * Named hidden inputs are skipped by React 19 hydration, preserving RSC markup.
+ * The gateway must reject missing/conflicting markers before admitting mutations.
+ */
+export function createReleaseFormTransform({ deploymentId, documentUrl }) {
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(deploymentId))
+        throw new Error('Invalid Artifact release identifier');
+    const document = new URL(documentUrl);
+    if (!['https:', 'http:'].includes(document.protocol))
+        throw new Error('Invalid Artifact document URL');
+    const marker = `<input type="hidden" name="__sequence_release" value="${deploymentId}">`;
+    const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+    const encoder = new TextEncoder();
+    let baseUrl = document;
+    let hasBase = false;
+    let sourceOffset = 0;
+    let insertionOffsets = [];
+    const tokenizer = new BoundedHtmlTokenizer({ sourceCodeLocationInfo: true }, {
+        onStartTag(token) {
+            const attributes = new Map(token.attrs.map(attribute => [attribute.name, attribute.value]));
+            if (token.tagName === 'base' && !hasBase && attributes.has('href')) {
+                hasBase = true;
+                try {
+                    baseUrl = new URL(attributes.get('href') ?? '', document);
+                }
+                catch { /* Invalid base falls back to document. */ }
+            }
+            if (token.tagName === 'form' &&
+                resolvesToApplication({ action: attributes.get('action'), baseUrl, documentUrl: document }) && token.location) {
+                insertionOffsets.push(token.location.endOffset);
+            }
+            if (token.tagName === 'script')
+                tokenizer.state = TokenizerMode.SCRIPT_DATA;
+            else if (rawTextElements.has(token.tagName))
+                tokenizer.state = TokenizerMode.RAWTEXT;
+            else if (token.tagName === 'textarea' || token.tagName === 'title')
+                tokenizer.state = TokenizerMode.RCDATA;
+            else if (token.tagName === 'plaintext')
+                tokenizer.state = TokenizerMode.PLAINTEXT;
+        },
+        onEndTag() { },
+        onComment() { },
+        onDoctype() { },
+        onEof() { },
+        onCharacter() { },
+        onNullCharacter() { },
+        onWhitespaceCharacter() { },
+    });
+    function transformText({ text, controller, final = false }) {
+        // Bound tokenizer work and buffers even if upstream sends a very large chunk.
+        for (let offset = 0; offset < text.length;) {
+            let end = Math.min(offset + PARSE_CHUNK_CHARACTERS, text.length);
+            // Do not re-encode one half of a decoded astral Unicode character.
+            const last = text.charCodeAt(end - 1);
+            if (end < text.length && last >= 0xd800 && last <= 0xdbff)
+                end--;
+            const part = text.slice(offset, end);
+            offset = end;
+            insertionOffsets = [];
+            tokenizer.write(part, false);
+            tokenizer.releaseConsumedText();
+            let partOffset = 0;
+            let output = '';
+            for (const insertionOffset of insertionOffsets) {
+                const relative = insertionOffset - sourceOffset;
+                output += part.slice(partOffset, relative) + marker;
+                partOffset = relative;
+            }
+            output += part.slice(partOffset);
+            sourceOffset += part.length;
+            controller.enqueue(encoder.encode(output));
+        }
+        if (final)
+            tokenizer.write('', true);
+    }
+    return new TransformStream({
+        transform(chunk, controller) { transformText({ text: decoder.decode(chunk, { stream: true }), controller }); },
+        flush(controller) { transformText({ text: decoder.decode(), controller, final: true }); },
+    });
+}

package/dist/server/request-context.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import type { NextArtifactBridgeBootstrap, NextArtifactInitialContext } from '../next/protocol.js';
+export declare const ARTIFACT_REQUEST_CONTEXT_HEADER = "x-sequence-artifact-context";
+export declare const ARTIFACT_RUNTIME_TOKEN_HEADER = "x-sequence-artifact-runtime";
+export declare const ARTIFACT_SERVER_REQUEST_PATH = "/api/artifact-studio/server/request";
+export declare const ARTIFACT_CONTEXT_MAX_AGE_SECONDS = 60;
+/** Public request context. No bearer credentials or secret values belong here. */
+export declare const artifactRequestContextSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    iss: z.ZodLiteral<"atlas-artifact-gateway">;
+    aud: z.ZodString;
+    sub: z.ZodString;
+    projectId: z.ZodString;
+    environment: z.ZodString;
+    mode: z.ZodEnum<{
+        preview: "preview";
+        published: "published";
+        development: "development";
+    }>;
+    deploymentId: z.ZodNullable<z.ZodString>;
+    devSessionId: z.ZodNullable<z.ZodString>;
+    requestId: z.ZodString;
+    method: z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        DELETE: "DELETE";
+        HEAD: "HEAD";
+        PUT: "PUT";
+        PATCH: "PATCH";
+        OPTIONS: "OPTIONS";
+    }>;
+    path: z.ZodString;
+    iat: z.ZodNumber;
+    exp: z.ZodNumber;
+    capabilities: z.ZodArray<z.ZodString>;
+    serviceAccountId: z.ZodNullable<z.ZodString>;
+    bridge: z.ZodObject<{
+        parentOrigin: z.ZodString;
+        channelId: z.ZodString;
+        nonce: z.ZodString;
+    }, z.core.$strict>;
+    theme: z.ZodEnum<{
+        dark: "dark";
+        light: "light";
+        system: "system";
+    }>;
+    lattice: z.ZodObject<{
+        runId: z.ZodNullable<z.ZodString>;
+        nodeId: z.ZodNullable<z.ZodString>;
+        stepId: z.ZodNullable<z.ZodString>;
+        processId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    taskRoutes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type ArtifactRequestContext = z.infer<typeof artifactRequestContextSchema>;
+export type ArtifactGatewayPublicKeys = Readonly<Record<string, string>>;
+export declare class ArtifactContextError extends Error {
+    constructor();
+}
+/** Only the gateway owns private keys. Applications pin platform-provided public keys. */
+export declare function verifyArtifactRequestContext({ token, publicKeys, projectId, environment, method, path, now }: {
+    token: string | null;
+    publicKeys: ArtifactGatewayPublicKeys;
+    projectId: string;
+    environment: string;
+    /** Route handlers supply these; RSC callers use the signed gateway request metadata. */
+    method?: string;
+    path?: string;
+    now?: number;
+}): ArtifactRequestContext;
+/** Safe props for the client bridge; intentionally excludes actor and runtime credentials. */
+export declare function getArtifactBrowserBootstrap(context: ArtifactRequestContext): NextArtifactBridgeBootstrap & {
+    initialContext: NextArtifactInitialContext;
+};