@cogito.ai/astryx-web 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentDock Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @cogito.ai/astryx-web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Mobile-first page archetypes and shared web design guidance for AgentDock projects.
+
+## Contents
+
+- `dock-landing`, `dock-workbench`, `dock-list`, `dock-form-flow`, `dock-settings`, and
+  `dock-editor-frame` page templates
+- Design-base documentation, starting with `pnpm exec astryx docs dock-design-base`
+- Agent guidance for creating pages from templates
+- `astryx-web samples` for repeatable visual review
+
+The list, form, settings, and editor templates replace Core templates with the same intent. Use
+`--package @astryxdesign/core` when the original is deliberately needed.
+
+## Visual samples
+
+```bash
+astryx-web samples \
+  --base-url http://localhost:3000 \
+  --route /zh-CN/settings \
+  --theme neutral \
+  --mode light \
+  --mode dark \
+  --size 390x844 \
+  --size 1440x900 \
+  --out design-samples
+```
+
+Set `CHROME_PATH` to the system Chrome executable. The command writes one PNG per combination and
+an `index.json` containing the rendered routes and source commit.
+
+## License
+
+MIT

package/astryx.integration.mjs

@@ -0,0 +1,15 @@
+/** @type {import('@astryxdesign/cli/authoring').AstryxIntegration} */
+export default {
+  docs: './docs',
+  templates: './templates',
+
+  agentDocs: {
+    append: [
+      'Create every page from a template. Put the page type last: write "mobile settings page", not "settings page on mobile".',
+      'Prefer the dock-* archetypes; when you know the one you need, run astryx template <id> directly.',
+      'Read astryx docs dock-design-base before UI work. Phone (390px) and desktop (1440px) are both first-class; touch targets are at least 44px.',
+      'Keep every string in the app catalogs, every color a token, every breakpoint a container query; no style attributes and no viewport media queries.',
+      'Before calling UI work done, render it at 390x844 and 1440x900 in light and dark and check it against astryx docs dock-visual-acceptance.',
+    ],
+  },
+}

package/bin/astryx-web.mjs

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from 'node:child_process'
+import { once } from 'node:events'
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const COMMAND = 'samples'
+const APPEARANCE_STORAGE_KEY = 'agentdock.appearance'
+
+function requiredValue(args, index, flag) {
+  const value = args[index + 1]
+  if (!value || value.startsWith('--')) {
+    throw new Error(`${flag} needs a value`)
+  }
+  return value
+}
+
+function parseSize(value) {
+  const match = /^(\d+)x(\d+)$/.exec(value)
+  if (!match) throw new Error(`invalid --size ${value}; expected WIDTHxHEIGHT`)
+  return { width: Number(match[1]), height: Number(match[2]) }
+}
+
+function parseStorage(value) {
+  const at = value.indexOf('=')
+  if (at <= 0) throw new Error(`invalid --storage ${value}; expected key=value`)
+  return [value.slice(0, at), value.slice(at + 1)]
+}
+
+export function parseArgs(argv) {
+  if (argv[0] !== COMMAND) {
+    throw new Error(`astryx-web only provides the ${COMMAND} command`)
+  }
+
+  const config = {
+    baseUrl: null,
+    routes: [],
+    themes: [],
+    modes: [],
+    sizes: [],
+    storage: {},
+    out: null,
+  }
+
+  for (let index = 1; index < argv.length; index += 1) {
+    const flag = argv[index]
+    if (flag === '--base-url') {
+      config.baseUrl = requiredValue(argv, index, flag)
+      index += 1
+    } else if (flag === '--route') {
+      config.routes.push(requiredValue(argv, index, flag))
+      index += 1
+    } else if (flag === '--theme') {
+      config.themes.push(requiredValue(argv, index, flag))
+      index += 1
+    } else if (flag === '--mode') {
+      config.modes.push(requiredValue(argv, index, flag))
+      index += 1
+    } else if (flag === '--size') {
+      config.sizes.push(parseSize(requiredValue(argv, index, flag)))
+      index += 1
+    } else if (flag === '--out') {
+      config.out = requiredValue(argv, index, flag)
+      index += 1
+    } else if (flag === '--storage') {
+      const first = requiredValue(argv, index, flag)
+      const [key, value] = parseStorage(first)
+      config.storage[key] = value
+      index += 1
+      while (argv[index + 1] && !argv[index + 1].startsWith('--')) {
+        const [nextKey, nextValue] = parseStorage(argv[index + 1])
+        config.storage[nextKey] = nextValue
+        index += 1
+      }
+    } else {
+      throw new Error(`unknown option ${flag}`)
+    }
+  }
+
+  for (const [name, value] of [
+    ['--base-url', config.baseUrl],
+    ['--out', config.out],
+  ]) {
+    if (!value) throw new Error(`${name} is required`)
+  }
+  for (const [name, values] of [
+    ['--route', config.routes],
+    ['--theme', config.themes],
+    ['--mode', config.modes],
+    ['--size', config.sizes],
+  ]) {
+    if (values.length === 0) throw new Error(`${name} is required at least once`)
+  }
+
+  new URL(config.baseUrl)
+  return config
+}
+
+export function routeSlug(route) {
+  const slug = route
+    .split(/[?#]/, 1)[0]
+    .replace(/^\/+|\/+$/g, '')
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return slug || 'root'
+}
+
+export function sampleFileName(route, theme, mode, size) {
+  return `${routeSlug(route)}__${theme}__${mode}__${size.width}x${size.height}.png`
+}
+
+function gitCommit(cwd) {
+  const result = spawnSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf8' })
+  return result.status === 0 ? result.stdout.trim() : null
+}
+
+async function waitForJson(url, timeoutMs = 15_000) {
+  const started = Date.now()
+  while (Date.now() - started < timeoutMs) {
+    try {
+      const response = await fetch(url)
+      if (response.ok) return await response.json()
+    } catch {
+      // Chrome has not opened the debugging endpoint yet.
+    }
+    await new Promise((resolveDelay) => setTimeout(resolveDelay, 100))
+  }
+  throw new Error(`Chrome debugging endpoint did not start: ${url}`)
+}
+
+class Cdp {
+  constructor(url) {
+    this.nextId = 1
+    this.pending = new Map()
+    this.listeners = new Set()
+    this.socket = new WebSocket(url)
+  }
+
+  async open() {
+    await new Promise((resolveOpen, rejectOpen) => {
+      this.socket.addEventListener('open', resolveOpen, { once: true })
+      this.socket.addEventListener('error', rejectOpen, { once: true })
+    })
+    this.socket.addEventListener('message', (event) => {
+      const message = JSON.parse(String(event.data))
+      if (message.id) {
+        const pending = this.pending.get(message.id)
+        if (!pending) return
+        this.pending.delete(message.id)
+        if (message.error) pending.reject(new Error(message.error.message))
+        else pending.resolve(message.result)
+        return
+      }
+      for (const listener of this.listeners) listener(message)
+    })
+  }
+
+  send(method, params = {}, sessionId) {
+    const id = this.nextId
+    this.nextId += 1
+    const payload = { id, method, params }
+    if (sessionId) payload.sessionId = sessionId
+    this.socket.send(JSON.stringify(payload))
+    return new Promise((resolveSend, rejectSend) => {
+      this.pending.set(id, { resolve: resolveSend, reject: rejectSend })
+    })
+  }
+
+  onMessage(listener) {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  close() {
+    this.socket.close()
+  }
+}
+
+function waitForNetworkIdle(cdp, sessionId, timeoutMs = 30_000) {
+  return new Promise((resolveIdle, rejectIdle) => {
+    let timeoutTimer = null
+
+    const finish = (error) => {
+      clearTimeout(timeoutTimer)
+      off()
+      if (error) rejectIdle(error)
+      else resolveIdle()
+    }
+    const off = cdp.onMessage((message) => {
+      if (message.sessionId !== sessionId) return
+      if (message.method === 'Page.lifecycleEvent' && message.params?.name === 'networkIdle') {
+        finish()
+      }
+    })
+    timeoutTimer = setTimeout(
+      () => finish(new Error('page did not reach network idle within 30 seconds')),
+      timeoutMs,
+    )
+  })
+}
+
+async function openSamplePage(cdp) {
+  const { targetId } = await cdp.send('Target.createTarget', { url: 'about:blank' })
+  const { sessionId } = await cdp.send('Target.attachToTarget', { targetId, flatten: true })
+  await cdp.send('Page.enable', {}, sessionId)
+  await cdp.send('Page.setLifecycleEventsEnabled', { enabled: true }, sessionId)
+  await cdp.send('Network.enable', {}, sessionId)
+  return { targetId, sessionId }
+}
+
+async function renderSample(cdp, page, config, storage, route, theme, mode, size, out) {
+  const { sessionId } = page
+  await cdp.send(
+    'Emulation.setDeviceMetricsOverride',
+    {
+      width: size.width,
+      height: size.height,
+      deviceScaleFactor: 1,
+      mobile: size.width < 600,
+    },
+    sessionId,
+  )
+
+  for (const [name, value] of Object.entries(storage)) {
+    await cdp.send(
+      'Network.setCookie',
+      {
+        name,
+        value,
+        url: config.baseUrl,
+        path: '/',
+        sameSite: 'Lax',
+      },
+      sessionId,
+    )
+  }
+
+  const idle = waitForNetworkIdle(cdp, sessionId)
+  const url = new URL(route, config.baseUrl).href
+  await cdp.send('Page.navigate', { url }, sessionId)
+  await idle
+
+  const screenshot = await cdp.send(
+    'Page.captureScreenshot',
+    { format: 'png', fromSurface: true, captureBeyondViewport: false },
+    sessionId,
+  )
+  const file = sampleFileName(route, theme, mode, size)
+  writeFileSync(join(out, file), Buffer.from(screenshot.data, 'base64'))
+  return {
+    file,
+    route,
+    theme,
+    mode,
+    size: `${size.width}x${size.height}`,
+    width: size.width,
+    height: size.height,
+  }
+}
+
+export async function runSamples(config, env = process.env) {
+  const chromePath = env.CHROME_PATH
+  if (!chromePath) {
+    throw new Error('CHROME_PATH must name the system Chrome executable')
+  }
+
+  const out = resolve(config.out)
+  mkdirSync(out, { recursive: true })
+  const profile = mkdtempSync(join(tmpdir(), 'astryx-web-chrome-'))
+  const port = 20_000 + Math.floor(Math.random() * 20_000)
+  const chrome = spawn(
+    chromePath,
+    [
+      '--headless=new',
+      '--disable-gpu',
+      '--no-first-run',
+      '--no-default-browser-check',
+      `--remote-debugging-port=${port}`,
+      `--user-data-dir=${profile}`,
+      'about:blank',
+    ],
+    { stdio: 'ignore' },
+  )
+
+  let cdp
+  let page
+  try {
+    const version = await waitForJson(`http://127.0.0.1:${port}/json/version`)
+    cdp = new Cdp(version.webSocketDebuggerUrl)
+    await cdp.open()
+    page = await openSamplePage(cdp)
+
+    const entries = []
+    for (const route of config.routes) {
+      for (const theme of config.themes) {
+        for (const mode of config.modes) {
+          for (const size of config.sizes) {
+            const storage = {
+              ...config.storage,
+              [APPEARANCE_STORAGE_KEY]: `${theme}.${mode}`,
+            }
+            entries.push(
+              await renderSample(cdp, page, config, storage, route, theme, mode, size, out),
+            )
+          }
+        }
+      }
+    }
+
+    const index = {
+      commit: gitCommit(process.cwd()),
+      routes: config.routes,
+      files: entries,
+    }
+    writeFileSync(join(out, 'index.json'), `${JSON.stringify(index, null, 2)}\n`)
+    return index
+  } finally {
+    if (page) {
+      await cdp.send('Target.closeTarget', { targetId: page.targetId }).catch(() => undefined)
+    }
+    cdp?.close()
+    if (chrome.exitCode === null) {
+      chrome.kill('SIGTERM')
+      await Promise.race([
+        once(chrome, 'exit'),
+        new Promise((resolveDelay) => setTimeout(resolveDelay, 5_000)),
+      ])
+    }
+    if (chrome.exitCode === null) chrome.kill('SIGKILL')
+    rmSync(profile, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
+  }
+}
+
+async function main() {
+  try {
+    const config = parseArgs(process.argv.slice(2))
+    const index = await runSamples(config)
+    console.log(`Rendered ${index.files.length} samples to ${resolve(config.out)}`)
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exitCode = 1
+  }
+}
+
+if (
+  process.argv[1] &&
+  realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+) {
+  await main()
+}

package/docs/dock-accessibility.doc.mjs

@@ -0,0 +1,24 @@
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export default {
+  type: 'generic',
+  name: 'dock-accessibility',
+  title: 'Dock Accessibility',
+  description: 'Heading, focus, status, and contrast requirements for every page.',
+  sections: [
+    {
+      title: 'Accessibility',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Exactly one `h1` per page (visually hidden when it would repeat navigation); headings in order.',
+            'Visible focus on every control; every action reachable by keyboard.',
+            'Status is never color-only.',
+            'Contrast at least 4.5:1 for body text and 3:1 for large text and controls.',
+          ],
+        },
+      ],
+    },
+  ],
+}

package/docs/dock-components.doc.mjs

@@ -0,0 +1,26 @@
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export default {
+  type: 'generic',
+  name: 'dock-components',
+  title: 'Dock Components',
+  description: 'Component selection and layout rules for Astryx and AgentDock pages.',
+  sections: [
+    {
+      title: 'Components',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Use Astryx first: {@command component <Name>}, {@command search <words>}.',
+            'Layout uses `Stack`, `Grid`, `Section`, `List`, and the app’s layout primitives, never raw `<div>`s.',
+            'Cards are the exception: only for an independently enterable unit (a module entry, a record awaiting a decision), one level deep, never around a form, list, section, or page.',
+            'Row actions: the recurring one stays visible; rare or destructive ones go into one end-aligned `MoreMenu` with icon and text. Never three buttons across a row.',
+            'Pick the control from the value’s shape: on/off → `Switch`; 2–3 named choices → `SegmentedControl`; 4 or more → `Selector`; a number → `NumberInput`; free text → `TextInput`; an action → `Button`.',
+            'No `style` attributes, no hard-coded colors, no viewport media queries.',
+          ],
+        },
+      ],
+    },
+  ],
+}

package/docs/dock-copy.doc.mjs

@@ -0,0 +1,23 @@
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export default {
+  type: 'generic',
+  name: 'dock-copy',
+  title: 'Dock Copy',
+  description: 'Catalog, naming, and concision rules for user-facing text.',
+  sections: [
+    {
+      title: 'Copy',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Every user-facing string lives in the app catalogs, with the same keys in every locale.',
+            'Delete paragraphs that only introduce a section. Keep the one line attached to a thing: a value’s status, a field’s format rule, an option’s description.',
+            'Name things by what they do, not by the technology behind them.',
+          ],
+        },
+      ],
+    },
+  ],
+}

package/docs/dock-design-base.doc.mjs

@@ -0,0 +1,35 @@
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export default {
+  type: 'generic',
+  name: 'dock-design-base',
+  title: 'Dock Design Base',
+  description:
+    'The product, layout, interaction, content, state, accessibility, and acceptance rules for AgentDock web pages.',
+  sections: [
+    {
+      title: 'Read the design base',
+      content: [
+        {
+          type: 'prose',
+          text: 'Read these sections before UI work. They apply to the same Web in the desktop App, the mobile App WebView, and a standalone browser.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '{@link generic:dock-product-stance}',
+            '{@link generic:dock-environment}',
+            '{@link generic:dock-layout}',
+            '{@link generic:dock-touch-mobile}',
+            '{@link generic:dock-components}',
+            '{@link generic:dock-copy}',
+            '{@link generic:dock-states}',
+            '{@link generic:dock-accessibility}',
+            '{@link generic:dock-refuse-list}',
+            '{@link generic:dock-visual-acceptance}',
+          ],
+        },
+      ],
+    },
+  ],
+}

package/docs/dock-environment.doc.mjs

@@ -0,0 +1,24 @@
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export default {
+  type: 'generic',
+  name: 'dock-environment',
+  title: 'Dock Environment',
+  description: 'The App, WebView, and browser surfaces that every page must support.',
+  sections: [
+    {
+      title: 'Environment',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'The same Web runs in three places: the TheFoolAI desktop App, where the package Web is the main surface; the mobile App’s WebView, on a phone with touch; and a standalone browser.',
+            'Phone (390×844) and desktop (1440×900) are both first-class design targets. The narrowest supported width is 360px.',
+            'Widths come from container queries, not the viewport: below 420px compact, 420–639px standard, 640–959px enhanced, 960px and up wide.',
+            'No horizontal scrolling at any width. A wide table becomes key–value rows or a named scrollable region.',
+          ],
+        },
+      ],
+    },
+  ],
+}

package/docs/dock-layout.doc.mjs

@@ -0,0 +1,25 @@
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export default {
+  type: 'generic',
+  name: 'dock-layout',
+  title: 'Dock Layout',
+  description: 'Page structure, spacing, reading width, and responsive layout rules.',
+  sections: [
+    {
+      title: 'Layout',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Inline padding 12px below 420px, 20px from 420px. Section gap 16px below 420px, 24px from 420px.',
+            'Reading content is capped at 44rem; grids may use 56rem from 960px.',
+            'Second-level pages use the one-screen skeleton (`PageShell`): the top bar stays, only the body scrolls.',
+            'Vertical first: put secondary detail behind a disclosure, a drawer, a sheet, or a sub-route instead of extending one long scroll.',
+            'Never print a title that repeats the navigation; keep a visually hidden `h1` instead.',
+          ],
+        },
+      ],
+    },
+  ],
+}

package/docs/dock-product-stance.doc.mjs

@@ -0,0 +1,25 @@
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export default {
+  type: 'generic',
+  name: 'dock-product-stance',
+  title: 'Dock Product Stance',
+  description: 'Product rules that keep every page focused on the user’s next action.',
+  sections: [
+    {
+      title: 'Product stance',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'One page, one job. A first-level route is an index; the work happens one route deeper.',
+            'Hierarchy over decoration. Headings, dividers, and spacing carry structure; borders, shadows, and card chrome are exceptions.',
+            'The first screen answers "what do I do now" with a control, not a paragraph.',
+            'Fewer, larger surfaces. If a page reads as a wall of boxes, remove boxes.',
+            'Every label, counter, and tip must earn its line.',
+          ],
+        },
+      ],
+    },
+  ],
+}

package/docs/dock-refuse-list.doc.mjs

@@ -0,0 +1,34 @@
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export default {
+  type: 'generic',
+  name: 'dock-refuse-list',
+  title: 'Dock Refuse List',
+  description: 'Visual and interaction patterns that must never ship.',
+  sections: [
+    {
+      title: 'Refuse list',
+      content: [
+        {
+          type: 'list',
+          style: 'dont',
+          items: [
+            'Gradient text',
+            'Glass or blur used as decoration',
+            'Neon glow on dark backgrounds',
+            'Colored side stripes on cards',
+            'Emoji used as icons',
+            'Cards inside cards',
+            'A page body that is a grid of identical cards',
+            'Big-number "hero metrics" on a page that is not a dashboard',
+            'Small caps "eyebrow" labels above every heading',
+            'Purple-to-blue gradients',
+            'Flows that open with a modal (use an inline step, a sheet, or a drawer)',
+            'More than one accent color',
+            'Reading lines longer than about 75 characters',
+            'Centered body paragraphs',
+          ],
+        },
+      ],
+    },
+  ],
+}

package/docs/dock-states.doc.mjs

@@ -0,0 +1,23 @@
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export default {
+  type: 'generic',
+  name: 'dock-states',
+  title: 'Dock States',
+  description: 'Loading, empty, error, disabled, and success state requirements.',
+  sections: [
+    {
+      title: 'States',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Every asynchronous surface has loading, empty, error (readable, with a retry), disabled, and success states.',
+            'An empty section is one line of text. `EmptyState` is only for a page whose whole purpose is empty.',
+            'A failed save never silently drops the user’s edit.',
+          ],
+        },
+      ],
+    },
+  ],
+}