@sequenceholdings/artifact-studio 0.2.5 → 0.2.6

package/README.md

@@ -0,0 +1,35 @@
+# Artifact Studio SDK
+
+`@sequenceholdings/artifact-studio` exposes the host-provided `seq` client. Runtime
+requests use the current user's normal permissions.
+
+Artifact Studio is a workflow-agnostic platform primitive. The host, SDK, and
+deployer provide generic application capabilities; each deployed artifact owns
+its product behavior. Primitive code must not branch on an artifact ID or import
+an application's services. See [Platform primitive boundaries](../../../docs/platform/platform-primitives.md).
+
+## Grouping calls into a trace
+
+The Artifact host supplies tracing context automatically for supported platform
+requests. Use an explicit action scope to correlate several calls from one UI
+action and supply a readable intent key:
+
+```ts
+import { withTraceAction } from '@sequenceholdings/artifact-studio'
+
+await withTraceAction(
+  { key: 'application.refresh' },
+  async ({ api, functions }) => {
+    await functions.invoke('my-function', { refresh: true })
+    await api.get('/api/my-application/summary')
+  },
+)
+```
+
+Use a stable operation label, never an identifier, customer value or payload. Each
+scope gets its own correlation ID, so concurrent actions remain separate. The
+helper scopes JSON `api.fetch/get/post/put/patch/delete` and `functions.invoke`;
+streaming and file-transfer helpers retain their ordinary host tracing behavior.
+Tracing does not grant permissions, change service-account behavior or guarantee
+that every transport is instrumented. Traces availability depends on the deployed
+platform version and your app/resource permissions.

package/VERSION-PIN.md

@@ -53,8 +53,12 @@ never claims `no-op` for a deploy that would actually rebuild.
 
 `tokens.css` is the canonical stylesheet and includes semantic roles plus the
 Tailwind utility bridge. The legacy `tokens.v2.css` and `theme.v2.css` paths are
-temporary forwarding aliases; the compiler normalizes their source imports to one
-canonical layer and reports a migration warning. An explicit
+temporary forwarding aliases in current packages; the compiler normalizes their
+source imports to one canonical layer and reports a migration warning only after
+checking that both selected files are forwarding aliases. Older packages carry
+independent styles in those files, so their imports and provenance entries are
+preserved. This prevents CRM spacing and corner utilities from disappearing when
+rebuilding with a split-sheet package. An explicit
 `seq-studio artifact dev --link <atlas-ui-package-dir>` preview additionally
 reports retired numbered black/white opacity utilities and uncertain dynamic
 class construction. Legacy stylesheet aliases normalize to canonical tokens;

package/dist/atlas-ui-css-plugin.d.ts

@@ -1,11 +1,15 @@
 import type { Plugin } from 'vite';
 export interface AtlasUiResolvedTokenSelection {
-    specifier: '@sequenceholdings/atlas-ui/tokens.css';
+    specifier: string;
     injectedBy: string | null;
 }
+/** Only collapse aliases when the selected package makes them forwarding sheets.
+ * Older releases define independent semantic tokens and the Tailwind bridge there.
+ */
+export declare function hasUnifiedAtlasUiTokens(atlasUiDir: string): boolean;
 /**
- * Every supported source shape becomes one canonical import before Tailwind
- * expands it. The aliases remain package-compatible, but are no longer allowed
+ * For packages with forwarding aliases, collapse imports before Tailwind
+ * expands them. The aliases remain package-compatible, but are no longer allowed
  * to create duplicate token layers in an Artifact Studio bundle (DES-437).
  */
 export declare function normalizeAtlasUiTokenImports(code: string): {
@@ -13,10 +17,10 @@ export declare function normalizeAtlasUiTokenImports(code: string): {
     deprecatedImports: string[];
 };
 /**
- * Evidence mirrors the CSS transform: aliases are normalized away, so the only
- * selected sheet is the canonical token entry point.
+ * Evidence mirrors the selected package: split sheets remain separate entries;
+ * forwarding aliases are normalized to the canonical entry point.
  */
-export declare function collectAtlasUiResolvedTokenSelections({ cssModules, }: {
+export declare function collectAtlasUiResolvedTokenSelections({ cssModules, atlasUiDir, }: {
     cssModules: readonly {
         id: string;
         code: string;
@@ -25,7 +29,7 @@ export declare function collectAtlasUiResolvedTokenSelections({ cssModules, }: {
     atlasUiDist: string;
     formRendererDist: string | null;
 }): AtlasUiResolvedTokenSelection[];
-export declare function atlasUiCssResolverPlugin({ atlasUiDir: _atlasUiDir, atlasUiDist, formRendererDist, onTransform, }: {
+export declare function atlasUiCssResolverPlugin({ atlasUiDir, atlasUiDist, formRendererDist, onTransform, }: {
     atlasUiDir: string;
     atlasUiDist: string;
     formRendererDist: string | null;

package/dist/atlas-ui-css-plugin.js

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -19,14 +19,26 @@ function resolveTwAnimateCssPath() {
 }
 const CANONICAL_TOKEN_IMPORT = '@import "@sequenceholdings/atlas-ui/tokens.css";';
 const ATLAS_UI_TOKEN_IMPORT = /@import\s+(?:url\(\s*)?(?:["'][^"']*?@sequenceholdings\/atlas-ui\/|[^"'()\s;]*@sequenceholdings\/atlas-ui\/)(tokens\.css|tokens\.v2\.css|theme\.v2\.css)(?:["'])?\s*\)?[^;\n]*;/gi;
+/** Only collapse aliases when the selected package makes them forwarding sheets.
+ * Older releases define independent semantic tokens and the Tailwind bridge there.
+ */
+export function hasUnifiedAtlasUiTokens(atlasUiDir) {
+    return ['tokens.v2.css', 'theme.v2.css'].every((sheet) => {
+        const path = resolve(atlasUiDir, sheet);
+        if (!existsSync(path))
+            return false;
+        const content = readFileSync(path, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '').trim();
+        return /^@import\s+["']@sequenceholdings\/atlas-ui\/tokens\.css["'];$/.test(content);
+    });
+}
 function atlasUiTokenImportSheets(code) {
     return [...code.matchAll(ATLAS_UI_TOKEN_IMPORT)]
         .map((match) => match[1]?.toLowerCase())
         .filter((sheet) => sheet !== undefined);
 }
 /**
- * Every supported source shape becomes one canonical import before Tailwind
- * expands it. The aliases remain package-compatible, but are no longer allowed
+ * For packages with forwarding aliases, collapse imports before Tailwind
+ * expands them. The aliases remain package-compatible, but are no longer allowed
  * to create duplicate token layers in an Artifact Studio bundle (DES-437).
  */
 export function normalizeAtlasUiTokenImports(code) {
@@ -43,16 +55,23 @@ export function normalizeAtlasUiTokenImports(code) {
     };
 }
 /**
- * Evidence mirrors the CSS transform: aliases are normalized away, so the only
- * selected sheet is the canonical token entry point.
+ * Evidence mirrors the selected package: split sheets remain separate entries;
+ * forwarding aliases are normalized to the canonical entry point.
  */
-export function collectAtlasUiResolvedTokenSelections({ cssModules, }) {
+export function collectAtlasUiResolvedTokenSelections({ cssModules, atlasUiDir, }) {
     for (const { code } of cssModules) {
         if (!code.includes('@import "tailwindcss"'))
             continue;
+        const sheets = atlasUiTokenImportSheets(code);
+        if (!hasUnifiedAtlasUiTokens(atlasUiDir)) {
+            return [...new Set(['tokens.css', ...sheets])].map((sheet) => ({
+                specifier: `@sequenceholdings/atlas-ui/${sheet}`,
+                injectedBy: sheets.includes(sheet) ? null : 'atlas-ui-css-resolver',
+            }));
+        }
         return [{
                 specifier: '@sequenceholdings/atlas-ui/tokens.css',
-                injectedBy: atlasUiTokenImportSheets(code).includes('tokens.css') ? null : 'atlas-ui-css-resolver',
+                injectedBy: sheets.includes('tokens.css') ? null : 'atlas-ui-css-resolver',
             }];
     }
     return [];
@@ -70,7 +89,8 @@ function insertAfterImports(code, lines) {
     const end = lastImport.index + lastImport[0].length;
     return `${code.slice(0, end)}${block}${code.slice(end)}`;
 }
-export function atlasUiCssResolverPlugin({ atlasUiDir: _atlasUiDir, atlasUiDist, formRendererDist, onTransform, }) {
+export function atlasUiCssResolverPlugin({ atlasUiDir, atlasUiDist, formRendererDist, onTransform, }) {
+    const unifiedTokens = hasUnifiedAtlasUiTokens(atlasUiDir);
     return {
         name: 'atlas-ui-css-resolver',
         enforce: 'pre',
@@ -88,8 +108,16 @@ export function atlasUiCssResolverPlugin({ atlasUiDir: _atlasUiDir, atlasUiDist,
                 if (formRendererDist) {
                     sources.push(`@source ${JSON.stringify(formRendererDist)};`);
                 }
-                const tokenImports = normalizeAtlasUiTokenImports(result);
-                result = tokenImports.code;
+                if (unifiedTokens) {
+                    result = normalizeAtlasUiTokenImports(result).code;
+                }
+                else if (!atlasUiTokenImportSheets(result).includes('tokens.css')) {
+                    const firstTokenImport = result.match(ATLAS_UI_TOKEN_IMPORT)?.[0];
+                    // The old base must precede the semantic overrides in split packages.
+                    result = firstTokenImport
+                        ? result.replace(firstTokenImport, `${CANONICAL_TOKEN_IMPORT}\n${firstTokenImport}`)
+                        : insertAfterImports(result, [CANONICAL_TOKEN_IMPORT]);
+                }
                 result = insertAfterImports(result, sources);
             }
             if (result.includes('@import "tw-animate-css"')) {

package/dist/build.js

@@ -3,7 +3,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, relative, resolve } from 'node:path';
 import { build as viteBuild } from 'vite';
-import { atlasUiCssResolverPlugin, collectAtlasUiResolvedTokenSelections } from './atlas-ui-css-plugin.js';
+import { atlasUiCssResolverPlugin, collectAtlasUiResolvedTokenSelections, hasUnifiedAtlasUiTokens } from './atlas-ui-css-plugin.js';
 import { validateAtlasUiTokenStylesheetContract } from './atlas-ui-package-contract.js';
 import { createObservedBuildEvidence } from './build-provenance.js';
 import { collectResolvedStylesheets } from './resolved-stylesheets.js';
@@ -31,6 +31,7 @@ const reactRouterDomDir = dirname(cliRequire.resolve('react-router-dom/package.j
 const sonnerDir = dirname(cliRequire.resolve('sonner'));
 const atlasUiDir = dirname(cliRequire.resolve('@sequenceholdings/atlas-ui/package.json'));
 const atlasUiDist = resolve(atlasUiDir, 'dist');
+const artifactSdkEntry = cliRequire.resolve('@sequenceholdings/artifact-studio');
 /**
  * Released Atlas UI 2.0.1 exports its canonical sheet from dist, while the
  * candidate layout puts the generated entry at package root so it can be read
@@ -75,6 +76,7 @@ function createPeerResolveAlias({ atlasUiPackageDir = atlasUiDir } = {}) {
         '@tanstack/react-query': reactQueryDir,
         'react-router-dom': reactRouterDomDir,
         sonner: sonnerDir,
+        '@sequenceholdings/storage': cliRequire.resolve('@sequenceholdings/storage'),
         // Candidate Atlas UI exposes canonical tokens at the package root; released
         // 2.0.1 keeps them in dist. Preserve explicit alias resolution so legacy
         // source reaches the normalizer instead of falling through to the bare alias.
@@ -102,7 +104,9 @@ export async function buildArtifactStudioProject(rootDir, { candidateTokenCompat
     const selectedAtlasUiTokens = resolveAtlasUiTokensPath(selectedAtlasUiDir);
     const source = await readArtifactStudioSource(rootDir);
     const diagnostics = [
-        ...collectDeprecatedTokenImportDiagnostics({ files: source.files }),
+        ...(hasUnifiedAtlasUiTokens(selectedAtlasUiDir)
+            ? collectDeprecatedTokenImportDiagnostics({ files: source.files })
+            : []),
         ...(candidateTokenCompatibility
             ? collectCandidateTokenCompatibilityDiagnostics({ files: source.files })
             : []),
@@ -116,7 +120,7 @@ export async function buildArtifactStudioProject(rootDir, { candidateTokenCompat
         plugins: [
             rejectOutsideSourcePlugin({
                 root,
-                trustedExternalRoots: Object.values(peerResolveAlias).map((target) => dirname(target)),
+                trustedExternalRoots: [...Object.values(peerResolveAlias).map((target) => dirname(target)), dirname(artifactSdkEntry)],
             }),
             rejectIgnoredSourcePlugin(root, source.ignorePatterns),
             artifactSdkVirtualModule(),
@@ -267,8 +271,8 @@ function artifactSdkVirtualModule() {
         // host-injected `window.seq`, so a tree that happens to be `pnpm install`ed
         // must produce the same bundle as a bare tree (e.g. one materialized from a
         // git repo) — otherwise the same source yields different bytes depending on
-        // whether node_modules exists. The package's sole runtime export is `seq`
-        // (everything else is type-only), so this stub is a complete substitute.
+        // whether node_modules exists. Use the CLI's SDK entry so runtime helpers
+        // stay in sync with the types instead of maintaining a partial export stub.
         enforce: 'pre',
         resolveId(id) {
             return virtualIds.has(id) ? resolved : undefined;
@@ -276,7 +280,7 @@ function artifactSdkVirtualModule() {
         load(id) {
             if (id !== resolved)
                 return undefined;
-            return 'export const seq = window.seq; export default window.seq;';
+            return `export * from ${JSON.stringify(artifactSdkEntry)}; export { default } from ${JSON.stringify(artifactSdkEntry)};`;
         },
     };
 }

package/dist/cli.d.ts

@@ -5,7 +5,6 @@ interface RemoteProject {
     id: string;
     slug: string;
     title: string;
-    visibility?: string;
     activeDeployment?: {
         version: string;
         sourceHash: string;

package/dist/cli.js

@@ -254,8 +254,7 @@ async function listCommand(args) {
             : project.activeDeploymentId
                 ? 'deployed'
                 : 'not deployed';
-        const visibility = project.visibility ? `  ${project.visibility}` : '';
-        console.log(`  ${project.slug}  id=${project.id}  [${active}]${visibility}  ${project.title}`);
+        console.log(`  ${project.slug}  id=${project.id}  [${active}]  ${project.title}`);
     }
     return 0;
 }
@@ -300,8 +299,6 @@ async function showCommand(args) {
     console.log(`  title:       ${project.title}`);
     if (project.description)
         console.log(`  description: ${project.description}`);
-    if (project.visibility)
-        console.log(`  visibility:  ${project.visibility}`);
     if (project.appEligible !== undefined)
         console.log(`  appEligible: ${project.appEligible ? 'yes' : 'no'}`);
     if (project.createdBy)
@@ -499,7 +496,6 @@ async function deployCommand(args) {
             linkConfigDir: spec.kind === 'local' ? source.dir : null,
             allowCreate: args.flags['no-create'] !== true,
             explicitProjectId,
-            envName: env.name,
         });
         const deployment = await uploadDeployment({ env: env.url, token, projectId: project.id, result, channel: 'active', provenance: source.provenance });
         console.log(`[seq-studio] deployed ${project.title} ${deployment.version}`);
@@ -589,9 +585,7 @@ async function devCommand(args) {
         // Resolve per push so the token refreshes across a long watch session.
         const token = await getRequiredToken(args);
         if (!projectId) {
-            // envName so a first-time `artifact dev` creation honors the manifest
-            // visibility too (and notes drift, once, when the project pre-exists).
-            const project = await ensureRemoteProject({ env: env.url, token, result, linkConfigDir: dir, envName: env.name });
+            const project = await ensureRemoteProject({ env: env.url, token, result, linkConfigDir: dir });
             projectId = project.id;
         }
         const deployment = await uploadDeployment({
@@ -771,21 +765,7 @@ export function activeDeploymentMatchesSkipPin({ active, sourceHash, peerVersion
     return (active.cliVersion === peerVersions.cliVersion &&
         active.atlasUiVersion === peerVersions.atlasUiVersion);
 }
-/**
- * Deploys never change a live project's visibility — the Studio sharing UI /
- * PATCH own that. The manifest's targets.<env>.visibility is honored at
- * project CREATION only; on drift, say so instead of silently ignoring the
- * field (which is how it read as decorative for a year).
- */
-function warnOnVisibilityDrift({ project, declared, envName }) {
-    if (!declared || !envName || !project.visibility || declared === project.visibility)
-        return;
-    console.warn(`[seq-studio] note: artifact.bundle.yml targets.${envName}.visibility is "${declared}" but the project is ` +
-        `"${project.visibility}" on this environment — deploys never change visibility. Update it in Studio sharing ` +
-        `(or PATCH /api/artifact-studio/projects/${project.id}) if the manifest is what you intend.`);
-}
-async function ensureRemoteProject({ env, token, result, linkConfigDir, allowCreate = true, explicitProjectId = null, envName = null }) {
-    const declaredVisibility = envName ? result.manifest.targets?.[envName]?.visibility : undefined;
+async function ensureRemoteProject({ env, token, result, linkConfigDir, allowCreate = true, explicitProjectId = null }) {
     if (explicitProjectId) {
         const data = await getJsonOr404({ baseUrl: env, token, path: `/api/artifact-studio/projects/${explicitProjectId}` });
         if (!data)
@@ -794,14 +774,12 @@ async function ensureRemoteProject({ env, token, result, linkConfigDir, allowCre
             throw new Error(`--project ${explicitProjectId} resolves to slug "${data.project.slug}" but this source's ` +
                 `artifact.bundle.yml declares project_id "${result.manifest.artifact.project_id}" — refusing to deploy over a different project`);
         }
-        warnOnVisibilityDrift({ project: data.project, declared: declaredVisibility, envName });
         return data.project;
     }
     const config = linkConfigDir ? await readLocalConfig(linkConfigDir) : {};
     if (config.projectId) {
         const data = await getJsonOr404({ baseUrl: env, token, path: `/api/artifact-studio/projects/${config.projectId}` });
         if (data) {
-            warnOnVisibilityDrift({ project: data.project, declared: declaredVisibility, envName });
             return data.project;
         }
         console.warn(`[seq-studio] cached projectId ${config.projectId} not found on ${env} — relinking by slug`);
@@ -810,7 +788,6 @@ async function ensureRemoteProject({ env, token, result, linkConfigDir, allowCre
     if (existing) {
         if (linkConfigDir)
             await writeLocalConfig({ ...config, projectId: existing.id, projectSlug: existing.slug }, linkConfigDir);
-        warnOnVisibilityDrift({ project: existing, declared: declaredVisibility, envName });
         return existing;
     }
     if (!allowCreate) {
@@ -826,7 +803,6 @@ async function ensureRemoteProject({ env, token, result, linkConfigDir, allowCre
             title: result.manifest.artifact.title,
             slug: result.manifest.artifact.project_id,
             description: result.manifest.artifact.description ?? null,
-            ...(declaredVisibility ? { visibility: declaredVisibility } : {}),
         },
     });
     if (linkConfigDir)

package/dist/manifest.d.ts

@@ -29,6 +29,11 @@ export declare const artifactStudioManifestSchema: z.ZodObject<{
         react: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<18>, z.ZodLiteral<19>]>>;
     }, z.core.$strip>>;
     capabilities: z.ZodDefault<z.ZodObject<{
+        storage: z.ZodOptional<z.ZodRecord<z.ZodUUID, z.ZodEnum<{
+            viewer: "viewer";
+            editor: "editor";
+            admin: "admin";
+        }>>>;
         data: z.ZodDefault<z.ZodObject<{
             read: z.ZodDefault<z.ZodArray<z.ZodString>>;
             write: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -57,12 +62,7 @@ export declare const artifactStudioManifestSchema: z.ZodObject<{
     }, z.core.$strip>>;
     targets: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         url: z.ZodString;
-        visibility: z.ZodDefault<z.ZodEnum<{
-            published: "published";
-            private: "private";
-            shared: "shared";
-        }>>;
-    }, z.core.$strip>>>;
+    }, z.core.$strict>>>;
     sidebarBadge: z.ZodOptional<z.ZodObject<{
         endpoint: z.ZodString;
         tone: z.ZodOptional<z.ZodEnum<{

package/dist/manifest.js

@@ -1,3 +1,4 @@
+import { storageScopesSchema } from '@sequenceholdings/storage';
 import { z } from 'zod';
 import { capabilityPinsSchema, customRolesBlockSchema, validateCapabilityPins, } from './manifest-custom-roles.js';
 import { normalizeArtifactPath } from './paths.js';
@@ -56,6 +57,7 @@ export const artifactStudioManifestSchema = z.object({
         react: z.union([z.literal(18), z.literal(19)]).default(18),
     }).default({ sdk: 'sequence', react: 18 }),
     capabilities: z.object({
+        storage: storageScopesSchema.optional(),
         data: z.object({
             read: z.array(z.string().min(1)).default([]),
             write: z.array(z.string().min(1)).default([]),
@@ -96,8 +98,7 @@ export const artifactStudioManifestSchema = z.object({
     }),
     targets: z.record(z.string().min(1), z.object({
         url: z.string().url(),
-        visibility: z.enum(['private', 'shared', 'published']).default('private'),
-    })).default({}),
+    }).strict()).default({}),
     sidebarBadge: sidebarBadgeSchema.optional(),
 }).superRefine((manifest, ctx) => {
     for (const message of validateCapabilityPins({

package/dist/sdk.d.ts

@@ -1,4 +1,22 @@
+import { type StartStorageUpload, type StorageUploadSession } from '@sequenceholdings/storage';
+export interface SequenceStorageOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    onProgress?: (progress: {
+        uploadId: string;
+        fileId: string;
+        uploadedBytes: number;
+    }) => void;
+}
+export interface SequenceStorage {
+    upload(workspaceId: string, input: StartStorageUpload, file: Blob, options?: SequenceStorageOptions): Promise<StorageUploadSession>;
+    resume(workspaceId: string, uploadId: string, file: Blob, options?: SequenceStorageOptions): Promise<StorageUploadSession>;
+}
 export interface SequenceApiFetchOptions {
+    traceAction?: {
+        id: string;
+        key: string;
+    };
     method?: string;
     body?: unknown;
     headers?: Record<string, string>;
@@ -7,6 +25,8 @@ export interface SequenceApiFetchResponse<TBody = unknown> {
     ok: boolean;
     status: number;
     body: TBody;
+    /** Allowlisted download headers for binary responses; keys are lowercase. */
+    headers?: Record<string, string>;
 }
 export interface SequenceApiUploadOptions {
     timeoutMs?: number;
@@ -28,7 +48,10 @@ export interface SequenceApi {
     delete<TBody = unknown>(path: string, body?: unknown): Promise<TBody>;
 }
 export interface SequenceFunctions {
-    invoke<TOutput = unknown>(id: string, params?: Record<string, unknown>): Promise<TOutput>;
+    invoke<TOutput = unknown>(id: string, params?: Record<string, unknown>, traceAction?: {
+        id: string;
+        key: string;
+    }): Promise<TOutput>;
 }
 export interface SequenceUser {
     current(): Promise<{
@@ -109,6 +132,7 @@ export interface SequenceHost {
     }): void;
 }
 export interface SequenceArtifactSdk {
+    storage: SequenceStorage;
     api: SequenceApi;
     ai: {
         fetch(path: string, options?: SequenceApiFetchOptions): Promise<Response>;
@@ -128,3 +152,398 @@ declare global {
 }
 export declare const seq: SequenceArtifactSdk;
 export default seq;
+/** Typed metadata API plus direct browser-host transfers for sandboxed Artifacts. */
+export declare function createArtifactStorageClient(sdk?: SequenceArtifactSdk): {
+    workspace(id: string): {
+        uploads: {
+            put: (input: StartStorageUpload, file: Blob, options?: SequenceStorageOptions) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "aborted" | "pending" | "complete";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            resume: (uploadId: string, file: Blob, options?: SequenceStorageOptions) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "aborted" | "pending" | "complete";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            start: (input: StartStorageUpload) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "pending" | "complete" | "aborted";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            get: (id: string) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "pending" | "complete" | "aborted";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            complete: (id: string, input?: import("@sequenceholdings/storage").CompleteStorageUpload) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "pending" | "complete" | "aborted";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            abort: (id: string) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "pending" | "complete" | "aborted";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+        };
+        get: () => Promise<{
+            id: string;
+            name: string;
+            description: string;
+            environment: string;
+            state: "active" | "trashed" | "purging";
+            revision: number;
+            createdAt: string;
+            role: "viewer" | "editor" | "admin" | "owner";
+            quotaBytes: number;
+            usedBytes: number;
+            reservedBytes: number;
+        }>;
+        delete: (expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            targetId: string | null;
+            kind: "purge" | "delete_version";
+            status: "queued" | "running" | "succeeded" | "failed";
+            completed: number;
+            total: number;
+            error: string | null;
+            createdAt: string;
+            updatedAt: string;
+            canRetry: boolean;
+        }>;
+        list: (options?: import("@sequenceholdings/storage").StorageListOptions & {
+            parentId?: string | null;
+            trash?: boolean;
+        }) => Promise<{
+            items: {
+                id: string;
+                workspaceId: string;
+                parentId: string | null;
+                name: string;
+                kind: "file" | "folder";
+                state: "active" | "trashed" | "purging";
+                restricted: boolean;
+                revision: number;
+                currentVersionId: string | null;
+                metadata: Record<string, string>;
+                createdAt: string;
+                updatedAt: string;
+                role: "viewer" | "editor" | "admin";
+                size: number | null;
+                contentType: string | null;
+            }[];
+            nextCursor: string | null;
+        }>;
+        getNode: (id: string) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        createFolder: (name: string, parentId?: string | null, { idempotencyKey, }?: {
+            idempotencyKey?: string;
+        }) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        update: (id: string, input: import("zod").input<typeof import("@sequenceholdings/storage").updateNodeSchema>) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        trash: (id: string, expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        restore: (id: string, expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        purge: (id: string, expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            targetId: string | null;
+            kind: "purge" | "delete_version";
+            status: "queued" | "running" | "succeeded" | "failed";
+            completed: number;
+            total: number;
+            error: string | null;
+            createdAt: string;
+            updatedAt: string;
+            canRetry: boolean;
+        }>;
+        download: (id: string, options?: {
+            versionId?: string;
+            preview?: boolean;
+        }) => Promise<{
+            url: string;
+            expiresAt: string;
+            preview: boolean;
+        }>;
+        versions: (id: string, options?: {
+            before?: number;
+            limit?: number;
+        }) => Promise<{
+            items: {
+                id: string;
+                fileId: string;
+                revision: number;
+                size: number;
+                checksum: string;
+                contentType: string;
+                createdAt: string;
+                createdBy: string;
+                state: "active" | "purging";
+            }[];
+            nextRevision: number | null;
+        }>;
+        restoreVersion: (id: string, versionId: string, expectedRevision: number) => Promise<{
+            id: string;
+            fileId: string;
+            revision: number;
+            size: number;
+            checksum: string;
+            contentType: string;
+            createdAt: string;
+            createdBy: string;
+            state: "active" | "purging";
+        }>;
+        deleteVersion: (id: string, versionId: string, expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            targetId: string | null;
+            kind: "purge" | "delete_version";
+            status: "queued" | "running" | "succeeded" | "failed";
+            completed: number;
+            total: number;
+            error: string | null;
+            createdAt: string;
+            updatedAt: string;
+            canRetry: boolean;
+        }>;
+        access: (id?: string) => Promise<{
+            revision: number;
+            restricted: boolean;
+            grants: {
+                type: "user" | "group" | "organization" | "service_account";
+                id: string;
+                role: "viewer" | "editor" | "admin";
+            }[];
+            owner: string | null;
+            inherited: boolean;
+            workspaceAdminOverride: true;
+            displayNames: Record<string, string>;
+        }>;
+        setAccess: (input: import("zod").input<typeof import("@sequenceholdings/storage").updateStorageAccessSchema>, id?: string) => Promise<{
+            revision: number;
+            restricted: boolean;
+            grants: {
+                type: "user" | "group" | "organization" | "service_account";
+                id: string;
+                role: "viewer" | "editor" | "admin";
+            }[];
+            owner: string | null;
+            inherited: boolean;
+            workspaceAdminOverride: true;
+            displayNames: Record<string, string>;
+        }>;
+        transferOwner: (principal: {
+            type: "user" | "service_account";
+            id: string;
+        }, expectedRevision: number) => Promise<{
+            revision: number;
+            restricted: boolean;
+            grants: {
+                type: "user" | "group" | "organization" | "service_account";
+                id: string;
+                role: "viewer" | "editor" | "admin";
+            }[];
+            owner: string | null;
+            inherited: boolean;
+            workspaceAdminOverride: true;
+            displayNames: Record<string, string>;
+        }>;
+        operations: (options?: {
+            before?: string;
+            limit?: number;
+            scope?: import("@sequenceholdings/storage").StorageOperationScope;
+        }) => Promise<{
+            items: {
+                id: string;
+                workspaceId: string;
+                targetId: string | null;
+                kind: "purge" | "delete_version";
+                status: "queued" | "running" | "succeeded" | "failed";
+                completed: number;
+                total: number;
+                error: string | null;
+                createdAt: string;
+                updatedAt: string;
+                canRetry: boolean;
+            }[];
+            nextCursor: string | null;
+        }>;
+        retryOperation: (id: string) => Promise<{
+            id: string;
+            workspaceId: string;
+            targetId: string | null;
+            kind: "purge" | "delete_version";
+            status: "queued" | "running" | "succeeded" | "failed";
+            completed: number;
+            total: number;
+            error: string | null;
+            createdAt: string;
+            updatedAt: string;
+            canRetry: boolean;
+        }>;
+    };
+    capabilities: () => Promise<{
+        canProvision: boolean;
+        uploadMethods: string[];
+    }>;
+    list: (options?: import("@sequenceholdings/storage").StorageListOptions) => Promise<{
+        items: {
+            id: string;
+            name: string;
+            description: string;
+            environment: string;
+            state: "active" | "trashed" | "purging";
+            revision: number;
+            createdAt: string;
+            role: "viewer" | "editor" | "admin" | "owner";
+            quotaBytes: number;
+            usedBytes: number;
+            reservedBytes: number;
+        }[];
+        nextCursor: string | null;
+    }>;
+    shared: (options?: import("@sequenceholdings/storage").StorageListOptions & {
+        trash?: boolean;
+    }) => Promise<{
+        items: {
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }[];
+        nextCursor: string | null;
+    }>;
+    apply: (manifest: import("@sequenceholdings/storage").WorkspaceManifest) => Promise<{
+        id: string;
+        name: string;
+        description: string;
+        environment: string;
+        state: "active" | "trashed" | "purging";
+        revision: number;
+        createdAt: string;
+        role: "viewer" | "editor" | "admin" | "owner";
+        quotaBytes: number;
+        usedBytes: number;
+        reservedBytes: number;
+    }>;
+};
+/** Explicit scope keeps concurrent browser actions isolated. The key is a safe
+ * author label, never a payload or an authentication claim. */
+export declare function withTraceAction<T>({ key, sdk }: {
+    key: string;
+    sdk?: SequenceArtifactSdk;
+}, run: (client: Pick<SequenceArtifactSdk, 'api' | 'functions'>) => Promise<T>): Promise<T>;

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/templates/react-vite/artifact.bundle.yml

@@ -29,4 +29,3 @@ capabilities:
 targets:
   local:
     url: http://localhost:5001
-    visibility: private

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "SDK types and CLI library for building Artifact Studio apps. Driven via `seq-studio artifact <sub>` (@sequenceholdings/studio-cli), which runs the `./cli` runCli export.",
   "type": "module",
   "exports": {
@@ -85,7 +85,8 @@
     "tw-animate-css": "^1.4.0",
     "vite": "8.0.16",
     "zod": "^4.1.13",
-    "@sequenceholdings/lattice-form-renderer": "0.1.3"
+    "@sequenceholdings/lattice-form-renderer": "0.1.3",
+    "@sequenceholdings/storage": "0.1.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/templates/react-vite/artifact.bundle.yml

@@ -29,4 +29,3 @@ capabilities:
 targets:
   local:
     url: http://localhost:5001
-    visibility: private