acrylblends 1.0.10 → 1.2.0

package/plugins/acryl-state/src/socket.ts

@@ -0,0 +1,96 @@
+/**
+ * State over a WebSocket. A server-sent event stream holds one of the browser's six connections per host for as long as the page lives, and an app that follows a few keys in
+ * several windows uses them all; a WebSocket is not one of those six, and one socket carries every key of a page.
+ *
+ * `GET /api/state/ws` upgrades. Up, one JSON message per frame: `{ "t": "sub", "key": "<key>" }` and `{ "t": "unsub", "key": "<key>" }`. Down: `{ "key": "<key>", "value": <json> }` once on
+ * `sub` and after every change, `{ "key": "<key>", "error": "<why>" }` for a key that cannot be followed, and `{ "t": "ping" }` every {@link SOCKET_HEARTBEAT_MS} so a page can tell a quiet
+ * socket from a dead one. `GET /api/state/client.js` is the browser module that speaks this (`watch(key, callback)`), with the event stream as its fallback.
+ *
+ * A WebSocket has no CORS, so the upgrade is checked here ({@link refuseStranger}): a loopback peer on this port with a loopback `Host`, and an `Origin` that, when the request has one,
+ * is exactly this app's own origin. A program on this machine that sends no `Origin` (a script, a test) is let in, as it is for the JSON and stream routes; a web page of another
+ * origin, and a name that only resolves to this machine (DNS rebinding), are not.
+ */
+
+import type { Context, MiddlewareHandler } from 'acryl-router'
+import type { UpgradeWebSocket } from 'acryl-router/helpers'
+import { loopbackAuthority } from 'acryl-router/middleware'
+import type { ReadonlyCell } from './cell.ts'
+
+/** How often the server writes a `ping`; a page gives up on a socket that is silent for three of these. */
+export const SOCKET_HEARTBEAT_MS = 15_000
+
+/** How many keys one socket may follow; a page watches a handful. */
+export const MAX_KEYS_PER_SOCKET = 256
+
+/** What the socket needs of the state service. */
+export interface Cells {
+  find(key: string): ReadonlyCell<unknown> | undefined
+}
+
+export interface StateSocketOptions {
+  readonly upgrade: UpgradeWebSocket
+  readonly heartbeatMs?: number
+}
+
+/** A refusal (403) unless the upgrade comes from this machine to this app, and from its own page when it comes from a page at all. */
+export function refuseStranger(c: Context): Response | undefined {
+  const authority = loopbackAuthority(c)
+  if (authority === undefined) return c.json({ error: 'request authority rejected' }, 403)
+  const origin = c.req.header('origin')
+  const site = c.req.header('sec-fetch-site')
+  if ((origin !== undefined && origin !== authority.origin) || (site !== undefined && site !== 'same-origin')) {
+    return c.json({ error: 'only this app\'s own page may follow its state' }, 403)
+  }
+  return undefined
+}
+
+/** The route handler that upgrades and follows keys of `cells` for as long as the socket is open. */
+export function stateSocket(cells: Cells, options: StateSocketOptions): MiddlewareHandler {
+  const heartbeatMs = options.heartbeatMs ?? SOCKET_HEARTBEAT_MS
+  return options.upgrade(() => {
+    const following = new Map<string, () => void>()
+    let beat: NodeJS.Timeout | undefined
+    return {
+      onOpen(_event, ws) {
+        beat = setInterval(() => {
+          try { ws.send(JSON.stringify({ t: 'ping' })) } catch { /* the close event follows */ }
+        }, heartbeatMs)
+        beat.unref()
+      },
+      onMessage(event, ws) {
+        if (typeof event.data !== 'string') return
+        let message: { t?: unknown, key?: unknown }
+        try { message = JSON.parse(event.data) as typeof message } catch { return }
+        if (typeof message.key !== 'string') return
+        const key = message.key
+        const tell = (frame: object): void => {
+          try { ws.send(JSON.stringify(frame)) } catch { /* the close event follows */ }
+        }
+        const value = (current: unknown): void => {
+          let text: string
+          try { text = JSON.stringify({ key, value: current === undefined ? null : current }) } catch { tell({ key, error: 'the value cannot be sent as JSON' }); return }
+          try { ws.send(text) } catch { /* the close event follows */ }
+        }
+        if (message.t === 'unsub') {
+          following.get(key)?.()
+          following.delete(key)
+          return
+        }
+        if (message.t !== 'sub') return
+        const cell = cells.find(key)
+        if (cell === undefined) { tell({ key, error: 'no such state' }); return }
+        const known = following.has(key)
+        if (!known && following.size >= MAX_KEYS_PER_SOCKET) { tell({ key, error: 'too many keys on one socket' }); return }
+        // A key asked for twice is answered again with its value, and followed once.
+        if (known) { value(cell.get()); return }
+        value(cell.get())
+        following.set(key, cell.subscribe(value))
+      },
+      onClose() {
+        if (beat !== undefined) clearInterval(beat)
+        for (const stop of following.values()) stop()
+        following.clear()
+      },
+    }
+  }, { textOnly: true })
+}

package/plugins/acryl-web-server/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "acryl-web-server",
+  "description": "The webServer port of a framework-hosted app: the node request/upgrade interface DSH's driver rows register on, backed by acryl-node-server's raw routes. Ours, so the chat driver's connection and gateway run on our host without DSH's web server.",
+  "requires": ["acryl-node-server"],
+  "inject": ["nodeServer"],
+  "provides": ["webServer"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  },
+  "mount": "mount it before the DSH driver rows that inject webServer (the chat connection and its gateway); the framework's page serving applies its index taps",
+  "entries": {
+    "": "src/index.ts"
+  }
+}

package/plugins/acryl-web-server/src/index.ts

@@ -0,0 +1,164 @@
+/**
+ * The `webServer` port for a framework-hosted app. DSH's driver rows (the chat's connection and its remote gateway) register node handlers with
+ * `webServer.register` and `webServer.registerUpgrade`; this plugin serves them on the framework's own node server, so those rows run unchanged
+ * while the HTTP host, the page and the client-module serving stay ours.
+ *
+ * It is the inverse of `acryl-router-http`: there the Host's web server serves a router prefix; here our node server presents the web-server
+ * interface a DSH row expects. The surface is deliberately small: `host` and `port` (what `acryl-web` reads), `register` (exact or prefix),
+ * `registerUpgrade` (one exact path), and the index taps the page serving applies. A row that needs more of DSH's interface gets the extra
+ * method here, named with the row that needs it - so this seam can shrink when a row goes away.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Duplex } from 'node:stream'
+import { Context, Service } from '@deepseek-ai/cordis'
+import type { NodeServer, RawRoute, RawUpgradeRoute } from 'acryl-node-server'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-web-server'
+
+/** Hard requirement: the node server whose raw routes carry these handlers. */
+export const inject = ['nodeServer']
+
+/** A node handler at a path `exact` (the pathname itself) or a `prefix` (the path and everything below it). */
+export interface WebServerRoute {
+  readonly kind: 'prefix' | 'exact'
+  readonly path: string
+  readonly handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+}
+
+/** One exact-path upgrade handler; the socket belongs to the handler once its path matches. */
+export interface WebServerUpgradeRoute {
+  readonly path: string
+  readonly handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>
+}
+
+/** Transforms the served index document, in registration order. */
+export type IndexTap = (html: string) => string
+
+/** What a driver row (or `acryl-web`) reads from `webServer`. */
+export interface WebServerService {
+  /** The address the node server bound. */
+  readonly host: string
+  readonly port: number
+  /** Serve `route` until the returned remover runs or the calling plugin unloads. A path already served throws. */
+  register(route: WebServerRoute): () => void
+  /** Claim `route.path` for an upgrade until the returned remover runs or the calling plugin unloads. */
+  registerUpgrade(route: WebServerUpgradeRoute): () => void
+  /** Transform the served index document while the caller lives; returns its remover. */
+  tapIndex(transform: IndexTap): () => void
+  /** The document with the structured injection rows (the client modules' boot wire) and then every live tap applied. */
+  index(html: string): string
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    webServer: WebServerService
+  }
+}
+
+/** One structured index-injection row (DSH's contract): the kinds the client modules and a door script use. */
+interface IndexRow {
+  readonly kind?: string
+  readonly placement?: 'head' | 'body'
+  readonly text?: string
+  readonly src?: string
+  readonly name?: string
+  readonly value?: unknown
+}
+
+/** The boot-readiness tail the client shell waits for, as DSH renders it. */
+const READY_MARKUP = '<script>(globalThis.__DSH_BOOT_READY__ ??= Promise.withResolvers()).resolve()</script>'
+
+/** A JSON literal safe inside a `<script>`: a sequence like `</script>` must not end it. */
+const scriptJson = (value: unknown): string => JSON.stringify(value).replaceAll('</', '<\\/')
+
+/** Render one row; an unknown kind is skipped rather than emitted as broken markup. */
+function rowMarkup(row: IndexRow): string {
+  if (row.kind === 'script') return `<script>${row.text ?? ''}</script>`
+  if (row.kind === 'script-src') return `<script type="module" crossorigin src="${row.src ?? ''}"></script>`
+  if (row.kind === 'script-preload') return `<link rel="modulepreload" crossorigin href="${row.src ?? ''}" />`
+  if (row.kind === 'global') return `<script>globalThis[${scriptJson(row.name ?? '')}] = ${scriptJson(row.value)}</script>`
+  return ''
+}
+
+/** Insert each group after its opening tag, as DSH's served index does; a document without the tag gets the group first. */
+export function renderIndexRows(html: string, rows: readonly IndexRow[]): string {
+  let head = ''
+  let body = ''
+  for (const row of rows) {
+    const markup = rowMarkup(row)
+    if (markup === '') continue
+    if (row.placement === 'body') body += markup
+    else head += markup
+  }
+  body += READY_MARKUP
+  let document = html
+  const headOpen = /<head(?:\s[^>]*)?>/iu.exec(document)
+  if (head !== '') {
+    const at = headOpen === null ? 0 : headOpen.index + headOpen[0].length
+    document = `${document.slice(0, at)}${head}${document.slice(at)}`
+  }
+  const bodyOpen = /<body(?:\s[^>]*)?>/iu.exec(document)
+  if (body !== '') {
+    const at = bodyOpen === null ? document.length : bodyOpen.index + bodyOpen[0].length
+    document = `${document.slice(0, at)}${body}${document.slice(at)}`
+  }
+  return document
+}
+
+/** The port, backed by `nodeServer`'s raw routes; every registration belongs to the plugin that made it. */
+export class WebServer extends Service implements WebServerService {
+  private readonly taps: IndexTap[] = []
+
+  constructor(ctx: Context) {
+    super(ctx, 'webServer')
+  }
+
+  get host(): string {
+    return this.ctx.nodeServer.hostname
+  }
+
+  get port(): number {
+    return this.ctx.nodeServer.port
+  }
+
+  register(route: WebServerRoute): () => void {
+    const remove = this.ctx.nodeServer.registerRaw(route as RawRoute)
+    this.ctx.effect(() => () => { remove() }, `acryl-web-server: ${route.kind} ${route.path}`)
+    return remove
+  }
+
+  registerUpgrade(route: WebServerUpgradeRoute): () => void {
+    const remove = this.ctx.nodeServer.registerRawUpgrade(route as RawUpgradeRoute)
+    this.ctx.effect(() => () => { remove() }, `acryl-web-server: upgrade ${route.path}`)
+    return remove
+  }
+
+  tapIndex(transform: IndexTap): () => void {
+    this.taps.push(transform)
+    const remove = (): void => {
+      const at = this.taps.indexOf(transform)
+      if (at >= 0) this.taps.splice(at, 1)
+    }
+    this.ctx.effect(() => () => { remove() }, 'acryl-web-server: index tap')
+    return remove
+  }
+
+  index(html: string): string {
+    // The rows are DSH's index-injection contract (`webserver/index-inject`): the client-module row pushes its boot wire there. The rows render
+    // first, the string taps after, the same order DSH's own web server uses.
+    const rows: IndexRow[] = []
+    ;(this.ctx as unknown as { emit(name: string, table: IndexRow[]): void }).emit('webserver/index-inject', rows)
+    let document = renderIndexRows(html, rows)
+    for (const tap of [...this.taps]) document = tap(document)
+    return document
+  }
+}
+
+/** Provide `webServer` on this context; the node server must already be up (the plugin injects it). */
+export function apply(ctx: Context): void {
+  new WebServer(ctx)
+}
+
+/** Re-exported for callers that shape their own routes: the raw types the port is built on. */
+export type { NodeServer, RawRoute, RawUpgradeRoute }

package/plugins/agent/agent.ts

@@ -24,6 +24,8 @@ export type RunResult = (
 export interface RunOptions {
   /** Aborting it stops the run: the model call or tool in flight is dropped and the run ends `{ status: 'cancelled' }`. */
   readonly signal?: AbortSignal
+  /** The door's id of the page the run was asked from: every tool call carries it, so the page tools drive that page and no other (a production assistant serves many visitors). */
+  readonly page?: string
 }
 
 export interface Agent {
@@ -39,6 +41,16 @@ export interface Budget {
 export interface AgentConfig {
   /** Steps per run before it stops. */
   steps?: number
+  /**
+   * The only tools a run may see and call; absent: every tool in the registry. A production assistant gets the page tools alone (`door_look`, `door_act`), so whatever
+   * a visitor asks, the agent can use the app and never change it. A call to any other name fails as an unknown tool would.
+   */
+  tools?: readonly string[]
+  /**
+   * The tool whose result an answer must come right after. When the model answers after another tool call (it acted and did not look), the agent calls this tool
+   * itself, once, and asks the model again with what it shows. The production assistant sets `door_look`, so what it tells a visitor is what the page shows now.
+   */
+  answerAfter?: string
 }
 
 /**
@@ -91,6 +103,8 @@ export const agent = {
   inject: ['model', 'tools', 'memory'],
   apply(ctx: Context, config?: AgentConfig) {
     const limit = config?.steps ?? 6
+    const allowed = config?.tools === undefined ? undefined : new Set(config.tools)
+    const answerAfter = config?.answerAfter
     let runs = 0
     ctx.provide('agent', {
       async run(question, options) {
@@ -104,13 +118,15 @@ export const agent = {
         )
         // Assigned inside the run's fiber; `as` keeps TypeScript from narrowing it to this first value.
         let result = { status: 'budget_exceeded', steps: 0, trace } as RunResult
-        const task = ctx.plugin({
+        // Each run's `budget` is its own: runs may overlap (the production Assistant serves visitors at once), and a service name is shared unless isolated.
+        const task = ctx.isolate('budget').plugin({
           name: `task-${runs}`,
           inject: ['model', 'tools', 'memory'],
           async apply(scope: Context) {
             scope.provide('budget', { steps: 0, limit } satisfies Budget)
             const budget = scope.budget
             let toolResult: unknown
+            let looked = false
             while (budget.steps < budget.limit) {
               if (signal.aborted) {
                 result = { status: 'cancelled', steps: budget.steps, trace }
@@ -124,7 +140,7 @@ export const agent = {
                     step: budget.steps,
                     toolResult,
                     trace: [...trace],
-                    tools: scope.tools.list(),
+                    tools: scope.tools.list().filter((tool) => allowed?.has(tool.name) ?? true),
                     signal,
                   }),
                   signal,
@@ -136,16 +152,31 @@ export const agent = {
               }
               budget.steps += 1
               if (step.tool === undefined) {
-                scope.memory.remember(`${question} => ${step.text}`)
-                result = { status: 'completed', output: step.text, steps: budget.steps, trace }
-                return
-              }
+                const last = trace.at(-1)
+                const unseen =
+                  answerAfter !== undefined &&
+                  last !== undefined &&
+                  last.tool !== answerAfter &&
+                  !looked
+                if (!unseen) {
+                  scope.memory.remember(`${question} => ${step.text}`)
+                  result = { status: 'completed', output: step.text, steps: budget.steps, trace }
+                  return
+                }
+                step = { tool: answerAfter, input: {} }
+                looked = true
+              } else looked = false
               const call = record
                 ? recorder?.start(`tool:${step.tool}`, step.input, { parent: record.id })
                 : undefined
               try {
+                if (allowed !== undefined && !allowed.has(step.tool))
+                  throw new Error(`no tool named "${step.tool}" is allowed in this run`)
                 toolResult = await until(
-                  scope.tools.call(step.tool, step.input, { signal }),
+                  scope.tools.call(step.tool, step.input, {
+                    signal,
+                    ...(options?.page === undefined ? {} : { page: options.page }),
+                  }),
                   signal,
                 )
                 trace.push({

package/plugins/agent/index.ts

@@ -17,4 +17,4 @@ export {
   type Step,
   scripted,
 } from './model.ts'
-export { type Tool, type Tools, tools } from './tools.ts'
+export { type CallOptions, type Tool, type Tools, tools } from './tools.ts'

package/plugins/agent/model.ts

@@ -52,8 +52,16 @@ declare module '@deepseek-ai/cordis' {
 }
 
 const builtIn: Rule[] = [
-  ({ toolResult, step }) =>
-    step > 0 ? { text: `The answer is ${String(toolResult)}.` } : undefined,
+  ({ toolResult, step }) => {
+    if (step === 0) return undefined
+    // A failed call comes back as `{ error }`: say what failed, not "[object Object]".
+    const failed = typeof toolResult === 'object' && toolResult !== null && 'error' in toolResult
+    return {
+      text: failed
+        ? `That did not work: ${String(toolResult.error)}.`
+        : `The answer is ${String(toolResult)}.`,
+    }
+  },
   ({ question }) => {
     const sum = /^add\s+(-?\d+)\s+(-?\d+)$/.exec(question.trim())
     return sum ? { tool: 'add', input: [Number(sum[1]), Number(sum[2])] } : undefined

package/plugins/agent/tools.ts

@@ -1,12 +1,18 @@
 import type { Context } from '@deepseek-ai/cordis'
 
+/** What a run passes with each call: its signal, and the door's id of the page it was asked from (the page tools drive only that page). */
+export interface CallOptions {
+  readonly signal?: AbortSignal
+  readonly page?: string
+}
+
 /** One tool: what it does (for the model) and how to run it. */
 export interface Tool {
   readonly description: string
   /** The JSON Schema of the input (an object schema), sent to a real model so it knows which fields the tool takes. A tool without one takes any object. */
   readonly parameters?: Readonly<Record<string, unknown>>
-  /** `options.signal` aborts when the run is cancelled; a tool that can stop its work listens to it. */
-  run(input: unknown, options?: { signal?: AbortSignal }): unknown | Promise<unknown>
+  /** `options.signal` aborts when the run is cancelled; a tool that can stop its work listens to it. `options.page` is the page the run was asked from, when it was. */
+  run(input: unknown, options?: CallOptions): unknown | Promise<unknown>
 }
 
 /** The tool registry. A plugin registers its tools inside `ctx.effect`, so they leave with it. */
@@ -18,7 +24,7 @@ export interface Tools {
     description: string
     parameters?: Readonly<Record<string, unknown>>
   }>
-  call(name: string, input: unknown, options?: { signal?: AbortSignal }): Promise<unknown>
+  call(name: string, input: unknown, options?: CallOptions): Promise<unknown>
 }
 
 declare module '@deepseek-ai/cordis' {

package/plugins/agent-panel/client/describe.ts

@@ -42,3 +42,60 @@ export function describeTool(data: Record<string, unknown>): string | undefined
   const failed = data.error ? ` failed: ${clip(String(data.error))}` : ''
   return `${tool}${input}${failed}`
 }
+
+/** What an act touched, from its result: the door's chat tool answers `done: link "My tasks" (detail); look again before the next act`, its verb `{ target }`. */
+function targetOf(result: unknown): { role?: string; name?: string } {
+  if (typeof result === 'string') {
+    const match = /^done: (\S+) "(.*)"(?: \(.*\))?; look again/u.exec(result)
+    return match === null ? {} : { role: match[1], name: match[2] }
+  }
+  if (typeof result !== 'object' || result === null) return {}
+  const target = (result as { target?: unknown }).target
+  if (typeof target !== 'object' || target === null) return {}
+  const { role, name } = target as { role?: unknown; name?: unknown }
+  return {
+    ...(typeof role === 'string' ? { role } : {}),
+    ...(typeof name === 'string' ? { name } : {}),
+  }
+}
+
+/**
+ * The Assistant's step on the page, as the person reads it under the answer: what it did, named the way the page names it. `ui.open("My tasks")`,
+ * `ui.fill("Due", "This week")`, `ui.click("Save")`, `ui.press("Enter")`. A look changes nothing, so it is left out unless it failed. The control's name comes from the
+ * act's result (the page says what it acted on); the ref is the fallback.
+ */
+export function describePageStep(data: Record<string, unknown>): string | undefined {
+  const failed = data.error ? ' failed' : ''
+  if (data.tool === 'door_look') return failed === '' ? undefined : 'ui.look() failed'
+  if (data.tool !== 'door_act') return describeTool(data)
+  const input = (typeof data.input === 'object' && data.input !== null ? data.input : {}) as Record<
+    string,
+    unknown
+  >
+  const target = targetOf(data.result)
+  const quoted = (value: unknown): string => JSON.stringify(clip(String(value ?? '')))
+  const op = typeof input.op === 'string' ? input.op : 'act'
+  const named =
+    typeof target.name === 'string' && target.name !== ''
+      ? quoted(target.name)
+      : typeof input.ref === 'string'
+        ? input.ref
+        : undefined
+  const [verb, args]: [string, readonly (string | undefined)[]] =
+    op === 'navigate'
+      ? ['open', [quoted(input.path)]]
+      : op === 'click' && target.role === 'link'
+        ? ['open', [named]]
+        : op === 'type'
+          ? ['fill', [named, quoted(input.text)]]
+          : op === 'select'
+            ? ['fill', [named, quoted(input.option)]]
+            : op === 'press'
+              ? ['press', [quoted(input.key)]]
+              : op === 'scroll'
+                ? ['scroll', [input.direction === undefined ? undefined : quoted(input.direction)]]
+                : op === 'wait'
+                  ? ['wait', [quoted(input.text ?? input.name)]]
+                  : [op, [named]]
+  return `ui.${verb}(${args.filter((arg) => arg !== undefined).join(', ')})${failed}`
+}

package/plugins/agent-panel/client/driver-pick.ts

@@ -0,0 +1,22 @@
+/**
+ * Which driver pick a finished terminal open may apply to. `choose()` can be in flight when the person picks
+ * another driver (the panel also restores a remembered terminal at start), and only the latest pick may win: a
+ * stale terminal must not replace the form the person chose.
+ */
+export interface PickGeneration {
+  /** Start a pick and return the token its result is settled with. */
+  begin(): number
+  /** True only while `generation` is still the latest pick. */
+  isCurrent(generation: number): boolean
+}
+
+export function createPickGeneration(): PickGeneration {
+  let generation = 0
+  return {
+    begin: () => {
+      generation += 1
+      return generation
+    },
+    isCurrent: (candidate) => candidate === generation,
+  }
+}

package/plugins/agent-panel/client/frame.ts

@@ -0,0 +1,51 @@
+/**
+ * The ACRYL frame's view as the app page sees it (ide/acryl-blends-frame/src/client/frame-view.ts): the frame's canvas hides the app's own build-time
+ * controls in Build and shows what production shows in Preview. The page is same-origin with the frame, so it reads the handle the frame publishes on
+ * its window through `window.parent`; a page opened directly has no such parent and keeps its own behavior.
+ */
+
+export const FRAME_VIEW_KEY: symbol = Symbol.for('acryl.frame.view')
+export const FRAME_MODE_EVENT = 'acryl:frame-mode'
+
+/** What the app page reads from `window.parent[FRAME_VIEW_KEY]`. */
+export interface FrameViewHandle {
+  readonly mode: 'build' | 'preview'
+}
+
+/**
+ * The frame's view handle when this page runs in the frame's canvas.
+ * @param win - the page's window.
+ * @returns the handle, or undefined when the page is the top window or its parent is cross-origin.
+ */
+export function frameViewOf(win: Window = window): FrameViewHandle | undefined {
+  try {
+    if (win.parent === win) return undefined
+    return (win.parent as unknown as Record<symbol, FrameViewHandle | undefined>)[FRAME_VIEW_KEY]
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Whether the panel is the production Assistant: the Host itself is the Assistant, or the app's production environment names it (ACRYL_ASSISTANT=on)
+ * and the page runs in the frame, whose Preview shows the app as production would.
+ * @param session - the panel's session from its Host.
+ * @param frame - the frame's view handle, if any.
+ */
+export function panelVariant(
+  session: { readonly assistant?: boolean; readonly assistantInProduction?: boolean },
+  frame: FrameViewHandle | undefined,
+): boolean {
+  if (session.assistant === true) return true
+  return frame !== undefined && session.assistantInProduction === true
+}
+
+/**
+ * Whether the panel shows at all: on a page opened directly, yes; in the frame, only in Preview, and only as the Assistant. Build is the builder's
+ * screen, where the app's own panel has no place over the canvas.
+ * @param frame - the frame's view handle, if any.
+ * @param assistant - whether this panel is the production Assistant (see {@link panelVariant}).
+ */
+export function panelVisible(frame: FrameViewHandle | undefined, assistant: boolean): boolean {
+  return frame === undefined || (frame.mode === 'preview' && assistant)
+}