@sequenceholdings/artifact-studio 0.2.6 → 0.3.1

package/dist/templates/nextjs/app/api/health/route.ts

@@ -0,0 +1,6 @@
+export function GET() {
+  return Response.json(
+    { ok: true, framework: 'nextjs' },
+    { headers: { 'Cache-Control': 'no-store' } },
+  )
+}

package/dist/templates/nextjs/app/components/counter.tsx

@@ -0,0 +1,19 @@
+'use client'
+
+import { useState } from 'react'
+import { Button } from '@sequenceholdings/atlas-ui/next'
+
+export function Counter() {
+  const [count, setCount] = useState(0)
+
+  return (
+    <div className="flex items-center gap-stack-group">
+      <Button type="button" onClick={() => setCount(value => value + 1)}>
+        Increment
+      </Button>
+      <output className="font-mono text-lg tabular-nums" aria-live="polite">
+        {count}
+      </output>
+    </div>
+  )
+}

package/dist/templates/nextjs/app/components/greeting-form.tsx

@@ -0,0 +1,38 @@
+'use client'
+
+import { useActionState } from 'react'
+import { Button, Input } from '@sequenceholdings/atlas-ui/next'
+import { greet, type GreetingState } from '../actions'
+
+const initialState: GreetingState = { message: '', error: null }
+
+export function GreetingForm() {
+  const [state, action, pending] = useActionState(greet, initialState)
+
+  return (
+    <form action={action} className="space-y-4">
+      <div className="space-y-2">
+        <label htmlFor="name" className="text-sm font-medium">Your name</label>
+        <Input
+          id="name"
+          name="name"
+          autoComplete="given-name"
+          required
+          maxLength={80}
+          aria-invalid={Boolean(state.error)}
+          aria-describedby="greeting-result"
+        />
+      </div>
+      <Button type="submit" disabled={pending}>
+        {pending ? 'Sending…' : 'Say hello'}
+      </Button>
+      <p
+        id="greeting-result"
+        aria-live="polite"
+        className={state.error ? 'text-sm text-destructive' : 'text-sm text-foreground-secondary'}
+      >
+        {state.error ?? state.message}
+      </p>
+    </form>
+  )
+}

package/dist/templates/nextjs/app/globals.css

@@ -0,0 +1,4 @@
+@import "tailwindcss";
+@import "@sequenceholdings/atlas-ui/tokens.css";
+
+@source "../node_modules/@sequenceholdings/atlas-ui/dist";

package/dist/templates/nextjs/app/layout.tsx

@@ -0,0 +1,27 @@
+import type { Metadata } from 'next'
+import { headers } from 'next/headers'
+import type { ReactNode } from 'react'
+import {
+  getArtifactBrowserBootstrap,
+  getArtifactRequestContext,
+} from '@sequenceholdings/artifact-studio/server'
+import { Providers } from './providers'
+import './globals.css'
+
+export const metadata: Metadata = {
+  title: '{{title}}',
+  description: 'A full-stack application managed by Atlas',
+}
+
+export default async function RootLayout({ children }: { children: ReactNode }) {
+  const context = await getArtifactRequestContext({ headers: await headers() })
+  const bootstrap = context ? getArtifactBrowserBootstrap(context) : null
+
+  return (
+    <html lang="en" className={bootstrap?.initialContext.theme?.dark ? 'dark' : undefined}>
+      <body className="min-h-screen bg-background font-sans text-foreground antialiased">
+        <Providers bootstrap={bootstrap}>{children}</Providers>
+      </body>
+    </html>
+  )
+}

package/dist/templates/nextjs/app/page.tsx

@@ -0,0 +1,51 @@
+import Link from 'next/link'
+import { connection } from 'next/server'
+import { Counter } from './components/counter'
+import { GreetingForm } from './components/greeting-form'
+
+export default async function HomePage() {
+  await connection()
+  const renderedAt = new Date().toISOString()
+
+  return (
+    <main className="mx-auto max-w-5xl px-roomy py-10 sm:px-8">
+      <header className="mb-10 border-b border-border pb-8">
+        <p className="mb-3 text-xs font-semibold uppercase tracking-widest text-primary">
+          Artifact Studio / Next.js
+        </p>
+        <h1 className="text-3xl font-semibold tracking-tight">{{title}}</h1>
+        <p className="mt-3 max-w-2xl text-foreground-secondary">
+          Build your interface and server together. Develop on your machine,
+          preview in Atlas and publish an application that runs independently.
+        </p>
+      </header>
+
+      <div className="grid gap-stack-section md:grid-cols-2">
+        <section className="rounded-lg border border-border bg-card p-6" aria-labelledby="client-heading">
+          <h2 id="client-heading" className="text-lg font-semibold">Client interaction</h2>
+          <p className="mb-6 mt-2 text-sm text-muted-foreground">
+            Increment the counter, then edit its label. Fast Refresh preserves
+            client state for compatible edits.
+          </p>
+          <Counter />
+        </section>
+
+        <section className="rounded-lg border border-border bg-card p-6" aria-labelledby="server-heading">
+          <h2 id="server-heading" className="text-lg font-semibold">Server action</h2>
+          <p className="mb-6 mt-2 text-sm text-muted-foreground">
+            Submit a name to a validated server action. This example does not
+            store data or require a connected resource.
+          </p>
+          <GreetingForm />
+        </section>
+      </div>
+
+      <footer className="mt-8 flex flex-wrap items-center justify-between gap-stack-group text-sm text-muted-foreground">
+        <p>Rendered on the server: <time dateTime={renderedAt}>{renderedAt}</time></p>
+        <Link href="/about" className="font-medium text-primary underline-offset-4 hover:underline">
+          How this application works
+        </Link>
+      </footer>
+    </main>
+  )
+}

package/dist/templates/nextjs/app/providers.tsx

@@ -0,0 +1,107 @@
+'use client'
+
+import { Suspense, useEffect, useRef, useState, type ReactNode } from 'react'
+import { usePathname, useRouter, useSearchParams } from 'next/navigation'
+import { PortalContainerProvider } from '@sequenceholdings/atlas-ui/next'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import {
+  createNextArtifactBridge,
+  createNextArtifactThemeApplier,
+  installNextArtifactBrowserIntegration,
+  type NextArtifactBridge,
+  type NextArtifactBridgeBootstrap,
+  type NextArtifactInitialContext,
+} from '@sequenceholdings/artifact-studio/next'
+
+type BrowserBootstrap = NextArtifactBridgeBootstrap & {
+  initialContext: NextArtifactInitialContext
+}
+
+export function Providers({ children, bootstrap }: {
+  children: ReactNode
+  bootstrap: BrowserBootstrap | null
+}) {
+  const [queryClient] = useState(() => new QueryClient())
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <PortalContainerProvider>
+        <Suspense fallback={null}>
+          <AtlasConnection bootstrap={bootstrap} />
+        </Suspense>
+        {children}
+      </PortalContainerProvider>
+    </QueryClientProvider>
+  )
+}
+
+function AtlasConnection({ bootstrap }: { bootstrap: BrowserBootstrap | null }) {
+  const router = useRouter()
+  const pathname = usePathname()
+  const searchParams = useSearchParams()
+  const currentBridge = useRef<NextArtifactBridge | null>(null)
+  const [connectionError, setConnectionError] = useState(false)
+
+  useEffect(() => {
+    if (!bootstrap) return
+    let active = true
+    const theme = createNextArtifactThemeApplier({ root: document.documentElement })
+    const bridge = createNextArtifactBridge({
+      bootstrap,
+      initialContext: bootstrap.initialContext,
+      onNavigate: ({ path, replace }) => replace ? router.replace(path) : router.push(path),
+    })
+    currentBridge.current = bridge
+    const removeBrowserIntegration = installNextArtifactBrowserIntegration({ bridge })
+    const applyTheme = () => {
+      const snapshot = bridge.getSnapshot()
+      if (snapshot.theme) theme.apply({ theme: snapshot.theme })
+    }
+    const updateRoute = () => bridge.routeChanged({
+      path: `${window.location.pathname}${window.location.search}${window.location.hash}`,
+    })
+    const updateTitle = () => {
+      if (bridge.getSnapshot().status === 'ready') {
+        bridge.setDocumentTitle({ label: document.title })
+      }
+    }
+    applyTheme()
+    const unsubscribe = bridge.subscribe(applyTheme)
+    const titleObserver = new MutationObserver(updateTitle)
+    titleObserver.observe(document.head, { childList: true, characterData: true, subtree: true })
+    window.addEventListener('hashchange', updateRoute)
+    updateRoute()
+    void bridge.connect().then(() => {
+      if (!active) return
+      setConnectionError(false)
+      updateTitle()
+    }).catch(() => {
+      if (active) setConnectionError(true)
+    })
+
+    return () => {
+      active = false
+      window.removeEventListener('hashchange', updateRoute)
+      titleObserver.disconnect()
+      unsubscribe()
+      removeBrowserIntegration()
+      bridge.dispose()
+      theme.dispose()
+      currentBridge.current = null
+    }
+  }, [bootstrap, router])
+
+  useEffect(() => {
+    const query = searchParams.toString()
+    currentBridge.current?.routeChanged({
+      path: `${pathname}${query ? `?${query}` : ''}${window.location.hash}`,
+    })
+  }, [pathname, searchParams])
+
+  if (!connectionError) return null
+  return (
+    <p role="alert" className="border-b border-border bg-card px-roomy py-default text-sm text-destructive">
+      The Atlas connection was interrupted. Reopen this preview from Artifact Studio.
+    </p>
+  )
+}

package/dist/templates/nextjs/artifact.bundle.yml

@@ -0,0 +1,55 @@
+bundle:
+  name: {{slug}}
+  schema_version: 2
+
+artifact:
+  project_id: {{slug}}
+  title: "{{title}}"
+  description: "A full-stack Next.js application managed by Atlas"
+  type: nextjs
+  app_root: .
+
+runtime:
+  sdk: sequence
+  react: 19
+  node: 24
+  next: '16.3'
+
+# Browser permissions and server permissions are separate declarations.
+capabilities:
+  data:
+    read: []
+    write: []
+  api:
+    read: []
+    write: []
+  functions:
+    invoke: []
+
+server:
+  capabilities:
+    data:
+      read: []
+      write: []
+    api:
+      read: []
+      write: []
+    functions:
+      invoke: []
+  secrets: []
+  egress: []
+  resources:
+    cpu: 1
+    memory_mb: 1024
+    concurrency: 20
+    min_instances: 0
+    max_instances: 3
+    timeout_seconds: 60
+
+build:
+  public_env: {}
+
+# Add a registered Atlas environment with `seq-studio artifact link -e <env>`.
+targets:
+  local:
+    url: http://localhost:5001

package/dist/templates/nextjs/gitignore

@@ -0,0 +1,9 @@
+node_modules/
+.next/
+next-env.d.ts
+.artifact/
+.artifact-studio/
+.env*
+*.tsbuildinfo
+coverage/
+.DS_Store

package/dist/templates/nextjs/next.config.mjs

@@ -0,0 +1,27 @@
+import { withArtifactNextConfig } from '@sequenceholdings/artifact-studio/next-cache/config'
+
+const devOrigin = process.env.ARTIFACT_STUDIO_DEV_ORIGIN
+
+function allowedDevOrigins() {
+  if (!devOrigin) return []
+  const url = new URL(devOrigin)
+  if (
+    !['http:', 'https:'].includes(url.protocol) ||
+    url.username || url.password || url.pathname !== '/' || url.search || url.hash ||
+    url.hostname.includes('*')
+  ) {
+    throw new Error('ARTIFACT_STUDIO_DEV_ORIGIN must be an exact HTTP(S) origin.')
+  }
+  // Next matches hostnames; the Atlas gateway validates the complete origin.
+  return [url.hostname]
+}
+
+/** @type {import('next').NextConfig} */
+const config = {
+  output: 'standalone',
+  poweredByHeader: false,
+  reactStrictMode: true,
+  allowedDevOrigins: allowedDevOrigins(),
+}
+
+export default withArtifactNextConfig(config)

package/dist/templates/nextjs/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "{{slug}}",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@10.28.2",
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "scripts": {
+    "dev": "next dev --webpack --hostname 127.0.0.1",
+    "build": "next build",
+    "start": "next start --hostname 127.0.0.1",
+    "type-check": "next typegen && tsc --noEmit"
+  },
+  "dependencies": {
+    "@sequenceholdings/artifact-studio": "{{artifactStudioVersion}}",
+    "@sequenceholdings/atlas-ui": "3.4.0",
+    "@tanstack/react-query": "^4.36.1",
+    "next": "16.3.4",
+    "react": "19.2.6",
+    "react-dom": "19.2.6",
+    "server-only": "0.0.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.2.2",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
+    "tailwindcss": "^4.2.2",
+    "typescript": "^5.6.0"
+  }
+}

package/dist/templates/nextjs/pnpm-workspace.yaml

@@ -0,0 +1,22 @@
+packages:
+  - '.'
+
+minimumReleaseAge: 10080
+# The Sequence SDK chain is published from the Studio repo's audited release
+# pipeline, so a new artifact-studio release must install without waiting out
+# the seven-day quarantine. Scoped to the exact first-party packages a fresh
+# scaffold resolves, not @sequenceholdings/*.
+minimumReleaseAgeExclude:
+  - '@sequenceholdings/artifact-studio'
+  - '@sequenceholdings/atlas-ui'
+  - '@sequenceholdings/custom-roles-manifest'
+  - '@sequenceholdings/lattice-form-renderer'
+  - '@sequenceholdings/orm'
+  - '@sequenceholdings/storage'
+strictDepBuilds: true
+allowBuilds:
+  '@tailwindcss/oxide': false
+  # Reached through the SDK's static builder and ORM tooling, never run by a
+  # Next.js app; its platform binary installs as an optional dependency.
+  esbuild: false
+  sharp: false

package/dist/templates/nextjs/postcss.config.mjs

@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+}

package/dist/templates/nextjs/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [{ "name": "next" }]
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts", ".next/dev/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/dist/templates/react-vite/package.json

@@ -9,7 +9,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@sequenceholdings/artifact-studio": "^0.2.4",
+    "@sequenceholdings/artifact-studio": "^0.3.0",
     "@sequenceholdings/atlas-ui": "^3.1.1",
     "@tailwindcss/postcss": "^4.2.2",
     "@tailwindcss/vite": "^4.2.2",

package/dist/trusted-install.js

@@ -1,5 +1,6 @@
 import { readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { load as parseYaml } from 'js-yaml';
 import { classifyLockfileOrigin } from './lockfile-origin.js';
 export class ArtifactInstallTrustError extends Error {
     name = 'ArtifactInstallTrustError';
@@ -20,6 +21,21 @@ const ALLOWED_TARBALL_PREFIXES = [
     'https://libraries.cgr.dev/javascript/',
     'https://libraries.cgr.dev/javascript-upstream/',
 ];
+/**
+ * Exact off-registry tarballs remote installs accept, each tied to one
+ * dependency name and one integrity hash the lockfile must pin. SheetJS ships
+ * 0.20.x only from its CDN; the registry stops at 0.18.5, which has known
+ * parser vulnerabilities.
+ */
+const PINNED_TARBALLS = new Map([
+    [
+        'https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz',
+        {
+            name: 'xlsx',
+            integrity: 'sha512-oLDq3jw7AcLqKWH2AhCpVTZl8mf6X2YReP+Neh0SJUzV/BdZYjth94tG5toiMB1PPrYtxOCfaoUCkvtuH+3AJA==',
+        },
+    ],
+]);
 const EXCLUDED_DIRS = new Set(['node_modules', '.git']);
 /** Platform peers the CLI aliases at build time — must not be prod-installed remotely. */
 export const REMOTE_INSTALL_PLATFORM_PACKAGES = new Set([
@@ -73,10 +89,15 @@ function assertNoPackageManagerSelection(pkg) {
         }
     }
 }
-function assertRegistryOnlySpecMap(map, label) {
+function isPinnedTarballSpec(name, spec) {
+    return typeof spec === 'string' && PINNED_TARBALLS.get(spec)?.name === name;
+}
+function assertRegistryOnlySpecMap(map, label, { allowPinnedTarballs = false } = {}) {
     if (!map || typeof map !== 'object')
         return;
     for (const [name, spec] of Object.entries(map)) {
+        if (allowPinnedTarballs && isPinnedTarballSpec(name, spec))
+            continue;
         if (isNonRegistrySpec(spec)) {
             throw new ArtifactInstallTrustError(`${label} "${name}" uses a non-registry spec ("${String(spec)}") — only registry semver ranges are allowed`);
         }
@@ -114,7 +135,7 @@ function assertRegistryOnlyPackageJson(dir) {
         throw new ArtifactInstallTrustError('package.json is not valid JSON');
     }
     for (const section of DEPENDENCY_SECTIONS) {
-        assertRegistryOnlySpecMap(pkg[section], 'Dependency');
+        assertRegistryOnlySpecMap(pkg[section], 'Dependency', { allowPinnedTarballs: true });
     }
     assertRegistryOnlySpecMap(pkg.resolutions, 'Resolution override');
     assertNoPackageManagerSelection(pkg);
@@ -148,6 +169,42 @@ function normalizeYamlScalar(raw) {
     }
     return trimmed;
 }
+/**
+ * Check resolved `packages` entries, not lockfile text, so a comment or a YAML
+ * form the text scan misses cannot stand in for a real resolution.
+ */
+function assertParsedPackageResolutions(lockfileText) {
+    let doc;
+    try {
+        doc = parseYaml(lockfileText);
+    }
+    catch {
+        throw new ArtifactInstallTrustError('pnpm-lock.yaml is not valid YAML');
+    }
+    const packages = doc && typeof doc === 'object' ? doc.packages : undefined;
+    if (!packages || typeof packages !== 'object')
+        return;
+    for (const [key, entry] of Object.entries(packages)) {
+        const resolution = entry && typeof entry === 'object'
+            ? entry.resolution
+            : undefined;
+        if (!resolution || typeof resolution !== 'object')
+            continue;
+        const { tarball, integrity } = resolution;
+        if (typeof tarball !== 'string')
+            continue;
+        const pinned = PINNED_TARBALLS.get(tarball);
+        if (pinned) {
+            if (!key.startsWith(`${pinned.name}@`) || integrity !== pinned.integrity) {
+                throw new ArtifactInstallTrustError(`pnpm-lock.yaml must pin integrity ${pinned.integrity} for ${pinned.name} from ${tarball} — regenerate the lockfile`);
+            }
+            continue;
+        }
+        if (!ALLOWED_TARBALL_PREFIXES.some((prefix) => tarball.startsWith(prefix))) {
+            throw new ArtifactInstallTrustError(`pnpm-lock.yaml tarball resolution "${tarball}" is not from the Chainguard registry`);
+        }
+    }
+}
 function assertChainguardLockfile(dir) {
     const lockfileText = readFileSync(join(dir, 'pnpm-lock.yaml'), 'utf8');
     if (classifyLockfileOrigin(lockfileText) !== 'chainguard') {
@@ -159,10 +216,13 @@ function assertChainguardLockfile(dir) {
     }
     for (const match of lockfileText.matchAll(LOCKFILE_TARBALL_RE)) {
         const tarball = normalizeYamlScalar(match[2] ?? '');
+        if (PINNED_TARBALLS.has(tarball))
+            continue;
         if (!ALLOWED_TARBALL_PREFIXES.some((prefix) => tarball.startsWith(prefix))) {
             throw new ArtifactInstallTrustError(`pnpm-lock.yaml tarball resolution "${tarball}" is not from the Chainguard registry`);
         }
     }
+    assertParsedPackageResolutions(lockfileText);
 }
 /**
  * Reject install-control files and non-registry dependency specs before a remote

package/dist/tunnel/broker.d.ts

@@ -0,0 +1,75 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { type TunnelLimits } from './peer.js';
+import type { TunnelRelay } from './transport.js';
+export interface TunnelLease {
+    sessionId: string;
+    epoch: number;
+    ownerId: string;
+    projectId: string;
+    environment: string;
+    expiresAt: number;
+    publicOrigin: string;
+}
+export interface TunnelOwner {
+    nodeId: string;
+    epoch: number;
+    expiresAt: number;
+}
+/** Production adapters must atomically fence epochs across nodes. Ingress routes
+ * to lookup().nodeId; this module never silently forwards to an arbitrary node. */
+export interface TunnelOwnershipStore {
+    claim(lease: TunnelLease, nodeId: string): Promise<boolean>;
+    lookup(sessionId: string): Promise<TunnelOwner | null>;
+    release(sessionId: string, epoch: number, nodeId: string): Promise<void>;
+}
+export interface GatewayAuthorization {
+    ownerId: string;
+    publicOrigin: string;
+    /** Signed, audience-scoped context minted by Atlas, never a user bearer. */
+    requestContext?: string;
+}
+export interface TunnelBrokerOptions {
+    nodeId: string;
+    routing: TunnelOwnershipStore;
+    authorizeTunnel(request: IncomingMessage): Promise<TunnelLease | null>;
+    authorizeRequest(request: IncomingMessage, sessionId: string): Promise<GatewayAuthorization | null>;
+    validateLease(lease: TunnelLease): Promise<boolean>;
+    relay?: TunnelRelay;
+    resolveLease?(sessionId: string): Promise<TunnelLease | null>;
+    onTunnelClosed?(lease: TunnelLease): void;
+    limits?: Partial<TunnelLimits>;
+}
+/** Transport only: all identity, cookie bootstrap and FGA checks belong to the
+ * mandatory Atlas callbacks. An unconfigured broker cannot accept connections. */
+export declare class ArtifactTunnelBroker {
+    private readonly options;
+    private readonly connections;
+    private readonly limits;
+    private readonly tunnels;
+    private readonly pendingConnections;
+    private readonly ownerTimers;
+    private closing;
+    constructor(options: TunnelBrokerOptions);
+    handleTunnelUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer): Promise<void>;
+    handleHttp(request: IncomingMessage, response: ServerResponse, sessionId: string): Promise<void>;
+    handleWebSocketUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, sessionId: string): Promise<void>;
+    private authorize;
+    private valid;
+    private remoteConnection;
+    private attach;
+    private receive;
+    private finish;
+    private abort;
+    /** Immediate revocation and graceful service shutdown hook. */
+    disconnect(sessionId: string): void;
+    close(): void;
+}
+/** For one-process local development/tests only. Production must provide a shared
+ * compare-and-swap store and route ingress to the claimed owner. */
+export declare class SingleProcessTunnelOwnership implements TunnelOwnershipStore {
+    private readonly owners;
+    claim(lease: TunnelLease, nodeId: string): Promise<boolean>;
+    lookup(sessionId: string): Promise<TunnelOwner | null>;
+    release(sessionId: string, epoch: number, nodeId: string): Promise<void>;
+}