@sequenceholdings/artifact-studio 0.2.6 → 0.3.1

package/templates/nextjs/README.md

@@ -0,0 +1,157 @@
+# Next.js on Artifact Studio
+
+This app uses Next.js App Router, React 19 and Node 24. Its source and development
+server live on your machine; Atlas manages access, previews and deployment. You
+do not need GCP credentials or a cloud devbox.
+
+## Get started
+
+Install Node 24, pnpm and a released `seq-studio` version with Next.js support.
+Your Atlas environment must have the Next.js runtime enabled.
+
+From this directory:
+
+```sh
+pnpm install
+seq-studio envs list
+seq-studio login --env <your-environment>
+seq-studio artifact link --env <your-environment>
+seq-studio artifact dev --env <your-environment>
+```
+
+Use an environment shown by `envs list`; for an OpCo, log in to that environment's
+realm. The CLI opens an owner-only preview in Atlas and connects it to Next.js
+over an authenticated outbound tunnel. Keep the process running while you edit.
+Use Ctrl+C to stop it. When your machine is offline, the preview is offline too.
+
+Local development uses Webpack with native Fast Refresh. This is the supported
+bundler for the pinned Next.js release; it preserves client navigation during
+updates through the Atlas preview. Dependency changes restart the
+local server; linked package edits rebuild and restart it. Changes to
+`artifact.bundle.yml` end the current session—restart `artifact dev` to authorize
+the new configuration and permissions.
+
+Commit the generated `pnpm-lock.yaml` with the app source. The workspace policy
+keeps the seven-day dependency age gate and explicit install-script decisions.
+Do not commit registry credentials or a project `.npmrc`.
+
+For a standalone UI check without Atlas, run `pnpm dev` and open the loopback URL.
+Atlas SDK calls require an authorized Atlas development session. The CLI sets
+`ARTIFACT_STUDIO_DEV_ORIGIN` for the exact preview host; do not replace it with a
+wildcard. Native Next.js routing is used throughout—no hash router or `basePath`.
+
+## What to edit
+
+| File | Purpose |
+| --- | --- |
+| `app/page.tsx` | Request-time Server Component and client interaction examples |
+| `app/actions.ts` | Validated server action; this example stores no data |
+| `app/api/health/route.ts` | App-owned route handler |
+| `app/providers.tsx` | Client boundary for the Atlas bridge, UI portals and React Query |
+| `app/about/page.tsx` | Nested route for exercising Atlas and Next navigation |
+| `artifact.bundle.yml` | Browser/server permissions and hosted runtime requirements |
+
+`app/layout.tsx` verifies the gateway's request context and passes only safe UI
+bootstrap data into the browser. Import Atlas UI components through
+`@sequenceholdings/atlas-ui/next`, which preserves their React client boundary.
+Keep `@sequenceholdings/artifact-studio/server` imports in
+Server Components, server actions or route handlers. Framework route/layout and
+configuration files use the default exports required by Next.js; other modules
+use named exports.
+
+Try incrementing the counter, then changing its label in
+`app/components/counter.tsx`. Compatible edits preserve its value through Fast
+Refresh. Submit the greeting form to exercise a server action; server validation
+still applies when browser validation is bypassed.
+
+## Data and secrets
+
+Browser permissions and server permissions are separate in the manifest. Add
+only the capabilities the application needs, then configure authorized resource
+bindings in Atlas. Local development uses explicit nonproduction resources and
+never falls back to production when a binding is missing.
+
+ORM access is declared per table and per mutation: list `<namespace>/<table>`
+under `data.read` for every table a query reads (queries that follow
+platform-user relations also read `<namespace>/platformUsers`). Under
+`data.write`, use `<namespace>/ops/<Operation>` for each persisted mutation the
+app runs, or `<namespace>/<table>` for table-level coverage.
+
+Managed secrets stay in hosted runtimes. For local integration tests, use your
+own test credentials, mocks or an existing governed function. Use a hosted
+preview for application code that needs a managed secret. Never put secrets in
+`build.public_env`, `NEXT_PUBLIC_*`, client components or committed files.
+
+The local process is ordinary code running as your operating-system user.
+Atlas governs access to platform resources; it does not sandbox your laptop's
+filesystem or all outbound network connections.
+
+## Build and deploy
+
+```sh
+pnpm type-check
+pnpm build
+seq-studio artifact plan --env <your-environment>
+seq-studio artifact deploy --repo <namespace>/<repository> --ref main --env <your-environment>
+```
+
+Push the reviewed application source and lockfile to its Git Service repository
+before deploying. The local build is a validation step. Atlas performs the official isolated build
+from recorded source and a lockfile, then operates the hosted Next.js server.
+Deployments do not depend on your laptop staying online. Reviewers use hosted
+previews rather than your owner-only local session.
+
+For official releases to deployed environments, use a clean reviewed `main`
+revision under the existing Artifact deployment policy. Inspect build/deployment
+status, permissions and runtime diagnostics in Artifact Studio. Failed runtime
+checks do not replace the previous healthy release.
+
+The default scaffold is dynamic and declares no distributed cache. Enable managed
+cache capacity in Atlas before adopting framework features that require shared
+cross-replica caching; local Fast Refresh is not a test of distributed cache
+behavior. Do not add a production cache endpoint or managed credentials to local
+environment files.
+
+## Toolchain updates
+
+This scaffold pins Next.js `16.3.4`, React/React DOM `19.2.6` and pnpm `10.28.2`,
+with Node major `24`. These are its selected versions, not a claim that they are
+the latest security releases. Use your platform's reviewed compatible versions
+when updating an existing app. The CLI and build path check the platform's exact
+approved Next/React selection; a different patch needs a coordinated platform
+update, even if it belongs to the same framework profile.
+
+For an approved patch, update the dependency declarations and lockfile together,
+run the local type/build checks, then verify a hosted preview before requesting
+an official repository-backed deployment. Existing immutable deployments keep
+their previous code until rebuilt and activated. Your platform team maintains
+build/runtime images and handles any urgent security response; this workflow
+does not require application authors to obtain cloud-provider credentials.
+
+## Images and fonts
+
+Keep static images and other binary assets in `public/`. Prefer committed WOFF2
+fonts loaded with `next/font/local`; compilation runs without unrestricted
+network access.
+
+For a public font prepared by the platform, add `build.public_fonts` entries with
+`path`, `url` and the actual lowercase `sha256` digest. Targets must be
+`public/fonts/<filename>.woff2`, without nested directories. Use ASCII
+letters/digits, hyphens or underscores for the basename, starting with a letter
+or digit. URLs must use HTTPS on `fonts.gstatic.com` with its versioned
+`/s/<family>/v<revision>/<file>.woff2` format and no query, fragment or custom
+port. The platform allows
+up to eight files, 2 MiB each and 8 MiB total, with no redirects. Connected local
+development prepares the same files. Existing matching files are reused;
+mismatches fail without overwriting your file. Load the result with
+`next/font/local`. A plain `pnpm build` uses files already present locally and
+does not prepare declared fonts. Do not use `next/font/google` to download during the
+network-blocked compilation stage.
+
+For a remote optimized image, add the exact HTTPS host to both Next's
+`images.remotePatterns` and the manifest's `server.egress`. Narrow the pathname
+to the content needed by the app. Wildcard hosts, custom ports, redirects,
+custom loaders, SVG optimization and private-IP destinations are unsupported.
+Remote bodies are capped at 10 MiB, or a lower configured limit. Keep the
+`withArtifactNextConfig` wrapper in place and verify remote images in a hosted
+preview under the application's actual egress policy.

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

@@ -0,0 +1,26 @@
+import Link from 'next/link'
+
+export default function AboutPage() {
+  return (
+    <main className="mx-auto max-w-3xl px-roomy py-10 sm:px-8">
+      <Link href="/" className="text-sm font-medium text-primary underline-offset-4 hover:underline">
+        Back to your application
+      </Link>
+      <h1 className="mb-6 mt-8 text-2xl font-semibold">One application, two runtimes</h1>
+      <div className="space-y-4 text-foreground-secondary">
+        <p>
+          Server Components, actions and route handlers execute on your local
+          Next.js process during development and in the managed runtime after deployment.
+        </p>
+        <p>
+          Client Components provide interactive UI in the browser. Import Atlas UI
+          components from a client module and use the server SDK only in server code.
+        </p>
+        <p>
+          Atlas controls access, resource bindings and deployment. Local development
+          uses explicit nonproduction bindings; managed secrets stay in hosted runtimes.
+        </p>
+      </div>
+    </main>
+  )
+}

package/templates/nextjs/app/actions.ts

@@ -0,0 +1,18 @@
+'use server'
+
+export interface GreetingState {
+  message: string
+  error: string | null
+}
+
+export async function greet(
+  _previousState: GreetingState,
+  formData: FormData,
+): Promise<GreetingState> {
+  const input = formData.get('name')
+  const name = typeof input === 'string' ? input.trim() : ''
+  if (name.length === 0 || name.length > 80) {
+    return { message: '', error: 'Enter a name between 1 and 80 characters.' }
+  }
+  return { message: `Hello, ${name}. Your server action ran successfully.`, error: null }
+}

package/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/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/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/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/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/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/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/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/templates/nextjs/gitignore

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

package/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/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/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/templates/nextjs/postcss.config.mjs

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

package/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/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",