@sequenceholdings/artifact-studio 0.2.6 → 0.3.1

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,75 @@
+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;
+    jti: z.ZodUUID;
+    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;
+};

package/dist/server/request-context.js

@@ -0,0 +1,107 @@
+import { createPublicKey, verify } from 'node:crypto';
+import { z } from 'zod';
+export const ARTIFACT_REQUEST_CONTEXT_HEADER = 'x-sequence-artifact-context';
+export const ARTIFACT_RUNTIME_TOKEN_HEADER = 'x-sequence-artifact-runtime';
+export const ARTIFACT_SERVER_REQUEST_PATH = '/api/artifact-studio/server/request';
+export const ARTIFACT_CONTEXT_MAX_AGE_SECONDS = 60;
+const id = z.string().min(1).max(255);
+const originSchema = z.string().max(2048).refine(value => {
+    try {
+        const url = new URL(value);
+        return value === url.origin && (url.protocol === 'https:' ||
+            (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)));
+    }
+    catch {
+        return false;
+    }
+}, 'Expected an HTTPS origin (HTTP is allowed only on loopback)');
+/** Public request context. No bearer credentials or secret values belong here. */
+export const artifactRequestContextSchema = z.object({
+    v: z.literal(1),
+    iss: z.literal('atlas-artifact-gateway'),
+    aud: z.string().min(1).max(300),
+    sub: id,
+    projectId: id,
+    environment: id,
+    mode: z.enum(['development', 'preview', 'published']),
+    deploymentId: id.nullable(),
+    devSessionId: id.nullable(),
+    /** Correlates logs, usage and audit records for the originating request. */
+    requestId: id,
+    /** Unique per signed context. Atlas budgets delegated calls per jti until the context expires. */
+    jti: z.uuid(),
+    /** The originating browser request's method. Atlas only delegates reads for GET, HEAD and OPTIONS. */
+    method: z.enum(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']),
+    path: z.string().min(1).max(8192).refine(value => value.startsWith('/') &&
+        !value.startsWith('//') && !/[\\\r\n\u0000#]/.test(value), 'Expected an origin-relative request path'),
+    iat: z.number().int().nonnegative(),
+    exp: z.number().int().positive(),
+    capabilities: z.array(id).max(256),
+    serviceAccountId: id.nullable(),
+    bridge: z.object({ parentOrigin: originSchema, channelId: id, nonce: z.string().min(16).max(255) }).strict(),
+    theme: z.enum(['light', 'dark', 'system']),
+    lattice: z.object({ runId: id.nullable(), nodeId: id.nullable(), stepId: id.nullable(), processId: id.nullable() }).strict(),
+    taskRoutes: z.array(z.string().min(1).max(512)).max(16).refine(routes => routes.join('').length <= 1024).optional(),
+}).strict().superRefine((value, ctx) => {
+    if (value.aud !== `artifact:${value.projectId}`)
+        ctx.addIssue({ code: 'custom', message: 'Invalid Artifact audience' });
+    if (value.exp <= value.iat || value.exp - value.iat > ARTIFACT_CONTEXT_MAX_AGE_SECONDS)
+        ctx.addIssue({ code: 'custom', message: 'Invalid Artifact context lifetime' });
+    if (value.mode === 'development' ? !value.devSessionId || value.deploymentId !== null : !value.deploymentId || value.devSessionId !== null)
+        ctx.addIssue({ code: 'custom', message: 'Artifact runtime identity does not match its mode' });
+});
+export class ArtifactContextError extends Error {
+    constructor() { super('Missing or invalid Artifact gateway request context'); this.name = 'ArtifactContextError'; }
+}
+function decode(value) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value))
+        throw new ArtifactContextError();
+    return JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+}
+/** Only the gateway owns private keys. Applications pin platform-provided public keys. */
+export function verifyArtifactRequestContext({ token, publicKeys, projectId, environment, method, path, now = Math.floor(Date.now() / 1000) }) {
+    try {
+        if (!token || token.length > 32768)
+            throw new ArtifactContextError();
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            throw new ArtifactContextError();
+        const [encodedHeader, encodedPayload, signature] = parts;
+        const header = z.object({ alg: z.literal('EdDSA'), typ: z.literal('JWT'), kid: id }).strict().parse(decode(encodedHeader));
+        const pem = Object.hasOwn(publicKeys, header.kid) ? publicKeys[header.kid] : undefined;
+        if (!pem || !/^[A-Za-z0-9_-]+$/.test(signature))
+            throw new ArtifactContextError();
+        const key = createPublicKey(pem);
+        if (key.asymmetricKeyType !== 'ed25519' ||
+            !verify(null, Buffer.from(`${encodedHeader}.${encodedPayload}`), key, Buffer.from(signature, 'base64url')))
+            throw new ArtifactContextError();
+        const context = artifactRequestContextSchema.parse(decode(encodedPayload));
+        if (context.projectId !== projectId || context.environment !== environment ||
+            context.exp <= now || context.iat > now + 5 ||
+            (method !== undefined && context.method !== method.toUpperCase()) || (path !== undefined && context.path !== path))
+            throw new ArtifactContextError();
+        Object.freeze(context.bridge);
+        Object.freeze(context.lattice);
+        Object.freeze(context.capabilities);
+        if (context.taskRoutes)
+            Object.freeze(context.taskRoutes);
+        return Object.freeze(context);
+    }
+    catch {
+        throw new ArtifactContextError();
+    }
+}
+/** Safe props for the client bridge; intentionally excludes actor and runtime credentials. */
+export function getArtifactBrowserBootstrap(context) {
+    return {
+        parentOrigin: context.bridge.parentOrigin,
+        channelId: context.bridge.channelId,
+        nonce: context.bridge.nonce,
+        deploymentId: context.deploymentId,
+        initialContext: {
+            theme: { tokens: null, theme: null, dark: context.theme === 'dark', vars: {} },
+            lattice: context.lattice,
+            route: context.path,
+        },
+    };
+}

package/dist/server/runtime-config.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+export declare const artifactRuntimeConfigSchema: z.ZodObject<{
+    atlasUrl: z.ZodString;
+    projectId: z.ZodString;
+    environment: z.ZodString;
+    sessionToken: z.ZodString;
+    publicKeys: z.ZodRecord<z.ZodString, z.ZodString>;
+    devSessionId: z.ZodOptional<z.ZodString>;
+    deploymentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ArtifactRuntimeConfig = z.infer<typeof artifactRuntimeConfigSchema>;
+export type ArtifactRequestHeaders = Pick<Headers, 'get'>;
+/** Credentials are platform-provided and rotated by the CLI, never inferred from ambient cloud auth. */
+export declare function readArtifactRuntimeConfig({ file }?: {
+    file?: string;
+}): Promise<ArtifactRuntimeConfig | null>;
+/** Null permits a standalone localhost page; platform services still require a verified gateway request. */
+export declare function getArtifactRequestContext({ headers, runtime, method, path }: {
+    headers: ArtifactRequestHeaders;
+    runtime?: ArtifactRuntimeConfig;
+    method?: string;
+    path?: string;
+}): Promise<{
+    v: 1;
+    iss: "atlas-artifact-gateway";
+    aud: string;
+    sub: string;
+    projectId: string;
+    environment: string;
+    mode: "preview" | "published" | "development";
+    deploymentId: string | null;
+    devSessionId: string | null;
+    requestId: string;
+    jti: string;
+    method: "GET" | "POST" | "DELETE" | "HEAD" | "PUT" | "PATCH" | "OPTIONS";
+    path: string;
+    iat: number;
+    exp: number;
+    capabilities: string[];
+    serviceAccountId: string | null;
+    bridge: {
+        parentOrigin: string;
+        channelId: string;
+        nonce: string;
+    };
+    theme: "dark" | "light" | "system";
+    lattice: {
+        runId: string | null;
+        nodeId: string | null;
+        stepId: string | null;
+        processId: string | null;
+    };
+    taskRoutes?: string[] | undefined;
+} | null>;

package/dist/server/runtime-config.js

@@ -0,0 +1,64 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { z } from 'zod';
+import { ARTIFACT_REQUEST_CONTEXT_HEADER, verifyArtifactRequestContext } from './request-context.js';
+const atlasOrigin = z.string().refine(value => {
+    try {
+        const url = new URL(value);
+        return value === url.origin && (url.protocol === 'https:' ||
+            (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)));
+    }
+    catch {
+        return false;
+    }
+}, 'Atlas URL must be an HTTPS origin (or loopback HTTP)');
+export const artifactRuntimeConfigSchema = z.object({
+    atlasUrl: atlasOrigin,
+    projectId: z.string().min(1).max(255),
+    environment: z.string().min(1).max(255),
+    sessionToken: z.string().min(16).max(16384),
+    publicKeys: z.record(z.string().min(1).max(255), z.string().min(1).max(8192)),
+    devSessionId: z.string().min(1).max(255).optional(),
+    deploymentId: z.string().min(1).max(255).optional(),
+}).strict().refine(value => !(value.devSessionId && value.deploymentId), 'Runtime cannot be both local and hosted');
+/** Credentials are platform-provided and rotated by the CLI, never inferred from ambient cloud auth. */
+export async function readArtifactRuntimeConfig({ file = process.env.SEQUENCE_ARTIFACT_RUNTIME_FILE } = {}) {
+    if (!file) {
+        const config = process.env.SEQUENCE_ARTIFACT_RUNTIME_CONFIG;
+        const sessionToken = process.env.SEQUENCE_ARTIFACT_RUNTIME_TOKEN;
+        if (config === undefined && sessionToken === undefined)
+            return null;
+        if (!config || !sessionToken || config.length > 65536)
+            throw new Error('Hosted Artifact runtime configuration is incomplete');
+        // Only the platform's explicit configuration is considered; never ambient cloud or CLI credentials.
+        const parsed = JSON.parse(config);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            throw new Error('Invalid hosted Artifact runtime configuration');
+        return artifactRuntimeConfigSchema.parse({ ...parsed, sessionToken });
+    }
+    const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > 65536 || (process.platform !== 'win32' && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.())))
+            throw new Error('Artifact runtime credential file must be owner-readable only, regular, and no larger than 64 KiB');
+        return artifactRuntimeConfigSchema.parse(JSON.parse(await handle.readFile('utf8')));
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Null permits a standalone localhost page; platform services still require a verified gateway request. */
+export async function getArtifactRequestContext({ headers, runtime, method, path }) {
+    const token = headers.get(ARTIFACT_REQUEST_CONTEXT_HEADER);
+    if (!token)
+        return null;
+    const config = runtime ? artifactRuntimeConfigSchema.parse(runtime) : await readArtifactRuntimeConfig();
+    if (!config)
+        throw new Error('Artifact runtime is not connected. Run seq-studio artifact dev or configure the hosted runtime.');
+    const context = verifyArtifactRequestContext({ token, publicKeys: config.publicKeys, projectId: config.projectId, environment: config.environment, method, path });
+    if (config.devSessionId && context.devSessionId !== config.devSessionId)
+        throw new Error('Artifact request belongs to a different development session');
+    if (config.deploymentId && context.deploymentId !== config.deploymentId)
+        throw new Error('Artifact request belongs to a different deployment');
+    return context;
+}

package/dist/server.d.ts

@@ -0,0 +1,8 @@
+import 'server-only';
+export { createArtifactServerClient, ArtifactServerError } from './server/client.js';
+export type { ArtifactOrmOperations, ArtifactServerClient, ArtifactServerFetchOptions } from './server/client.js';
+export { getArtifactRequestContext, readArtifactRuntimeConfig } from './server/runtime-config.js';
+export type { ArtifactRuntimeConfig, ArtifactRequestHeaders } from './server/runtime-config.js';
+export { getArtifactBrowserBootstrap } from './server/request-context.js';
+export type { ArtifactRequestContext } from './server/request-context.js';
+export type { ArtifactLogMetadata, ArtifactLogRecord } from './server/logger.js';

package/dist/server.js

@@ -0,0 +1,4 @@
+import 'server-only';
+export { createArtifactServerClient, ArtifactServerError } from './server/client.js';
+export { getArtifactRequestContext, readArtifactRuntimeConfig } from './server/runtime-config.js';
+export { getArtifactBrowserBootstrap } from './server/request-context.js';

package/dist/templates/nextjs/.artifactignore

@@ -0,0 +1,14 @@
+.git/
+node_modules/
+.next/
+next-env.d.ts
+.artifact/
+.artifact-studio/
+# Environment files are excluded by the source packager independently.
+.env
+.env.local
+.env.development.local
+.env.production.local
+tsconfig.tsbuildinfo
+coverage/
+.DS_Store

package/dist/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/dist/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/dist/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 }
+}