npm - acrylblends - Versions diffs - 1.0.10 → 1.2.0 - Mend

acrylblends 1.0.10 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (252) hide show

package/README.md +9 -0
package/dist/index.d.ts +60 -2
package/dist/index.js +1992 -33
package/dist/index.js.map +1 -1
package/docs/framework/agents/index.md +1 -1
package/docs/framework/api/summary.md +1 -1
package/docs/framework/getting-started/desktop.md +23 -4
package/docs/framework/guides/create-acrylblends.md +1 -1
package/docs/framework/guides/production.md +20 -0
package/docs/framework/workshop/README.md +174 -285
package/docs/framework/workshop/facilitator.md +81 -90
package/legacy/README.md +9 -0
package/legacy/agent/157ce3db1112/src/app.ts +98 -0
package/legacy/agent/157ce3db1112/src/routes.ts +63 -0
package/legacy/agent/24c681a00fca/src/app.ts +160 -0
package/legacy/agent/24c681a00fca/src/routes.ts +83 -0
package/legacy/agent/2e790da977b2/src/app.ts +98 -0
package/legacy/agent/2e790da977b2/src/routes.ts +63 -0
package/legacy/agent/6307045545dc/src/app.ts +168 -0
package/legacy/agent/6307045545dc/src/routes.ts +83 -0
package/legacy/agent/6a5fb9c15c53/src/app.ts +158 -0
package/legacy/agent/6a5fb9c15c53/src/routes.ts +83 -0
package/legacy/agent/71fb54a5a942/src/app.ts +111 -0
package/legacy/agent/71fb54a5a942/src/routes.ts +63 -0
package/legacy/agent/74ece148269c/src/app.ts +168 -0
package/legacy/agent/74ece148269c/src/routes.ts +93 -0
package/legacy/agent/855359304707/src/app.ts +168 -0
package/legacy/agent/855359304707/src/routes.ts +126 -0
package/legacy/agent/b5ef3c786ae4/src/app.ts +127 -0
package/legacy/agent/b5ef3c786ae4/src/routes.ts +76 -0
package/legacy/agent/c2f30958043b/src/app.ts +98 -0
package/legacy/agent/c2f30958043b/src/routes.ts +53 -0
package/legacy/blank/5a91c558af22/src/routes.ts +18 -0
package/legacy/blank/9c650cf52bf3/src/routes.ts +14 -0
package/legacy/blank/aea589283445/src/routes.ts +16 -0
package/legacy/blank/b2cbb759c889/src/routes.ts +16 -0
package/legacy/blank/d6d371c9a65e/src/routes.ts +18 -0
package/legacy/chat/7076cc821e2c/src/app.ts +72 -0
package/legacy/chat/7076cc821e2c/src/routes.ts +13 -0
package/legacy/chat/7dbe6d5170df/src/app.ts +107 -0
package/legacy/chat/7dbe6d5170df/src/routes.ts +19 -0
package/legacy/chat/a9a9ab44c58e/src/app.ts +107 -0
package/legacy/chat/a9a9ab44c58e/src/routes.ts +15 -0
package/legacy/chat/f20ad9a51b06/src/app.ts +106 -0
package/legacy/chat/f20ad9a51b06/src/routes.ts +15 -0
package/legacy/layouts.json +524 -0
package/legacy/nodejs/1d477f37aaf4/src/app.ts +92 -0
package/legacy/nodejs/1d477f37aaf4/src/routes.ts +40 -0
package/legacy/nodejs/b1bd9462496c/src/app.ts +61 -0
package/legacy/nodejs/b1bd9462496c/src/routes.ts +37 -0
package/legacy/nodejs/d5bab75076ef/src/app.ts +95 -0
package/legacy/nodejs/d5bab75076ef/src/routes.ts +40 -0
package/legacy/notes/4edc36949c15/src/app.ts +107 -0
package/legacy/notes/4edc36949c15/src/routes.ts +14 -0
package/legacy/notes/6cab2d09747c/src/app.ts +72 -0
package/legacy/notes/6cab2d09747c/src/routes.ts +12 -0
package/legacy/notes/7ca2dfed623a/src/app.ts +106 -0
package/legacy/notes/7ca2dfed623a/src/routes.ts +14 -0
package/legacy/todo/02e613b3625c/src/app.ts +71 -0
package/legacy/todo/02e613b3625c/src/todo.ts +123 -0
package/legacy/todo/45694a8d9e15/src/app.ts +71 -0
package/legacy/todo/45694a8d9e15/src/todo.ts +96 -0
package/legacy/todo/5923d3a6099f/src/app.ts +71 -0
package/legacy/todo/5923d3a6099f/src/todo.ts +125 -0
package/legacy/todo/849a18d66dc1/src/app.ts +91 -0
package/legacy/todo/849a18d66dc1/src/todo.ts +125 -0
package/legacy/todo/8e64211312f3/src/app.ts +71 -0
package/legacy/todo/8e64211312f3/src/todo.ts +125 -0
package/legacy/todo/b79078a87565/src/app.ts +71 -0
package/legacy/todo/b79078a87565/src/todo.ts +125 -0
package/lib/{audit-Dw-siYTp.d.ts → audit-Bok_UNCn.d.ts} +41 -6
package/lib/{client-modules-drj4mjhj.js → client-modules-Bkdr83jO.js} +1 -1
package/lib/cordis/door.d.ts +44 -7
package/lib/cordis/door.js +214 -60
package/lib/cordis/inspect.js +1 -1
package/lib/cordis/node-server.d.ts +101 -3
package/lib/cordis/node-server.js +3 -3
package/lib/cordis/router-http.d.ts +7 -1
package/lib/cordis/router-http.js +44 -3
package/lib/cordis/router.d.ts +1 -1
package/lib/cordis/router.js +1 -1
package/lib/cordis/state.d.ts +3 -2
package/lib/cordis/state.js +371 -7
package/lib/door/host.d.ts +2 -2
package/lib/door/host.js +1 -1
package/lib/door/page.d.ts +20 -1
package/lib/door/page.js +75 -14
package/lib/door/protocol.d.ts +1 -1
package/lib/drivers.d.ts +10 -1
package/lib/{index-DMOtA-NJ.d.ts → index-DGq7H0lb.d.ts} +11 -1
package/lib/node-server.d.ts +7 -1
package/lib/node-server.js +2 -2
package/lib/{protocol-a2aqrp2X.d.ts → protocol-BeIYCgTo.d.ts} +4 -0
package/lib/{snapshot-text-BfEbEOjA.js → snapshot-text-CXTnjxGx.js} +121 -9
package/lib/src-CtkIX_Gg.js +427 -0
package/lib/{src-BTBm4OPD.js → src-iBJ2ysV9.js} +77 -14
package/lib/{test-websocket-BLeEvybj.js → test-websocket-CQOSvBth.js} +17 -7
package/lib/{test-websocket-DyeS50Tr.d.ts → test-websocket-GUTAkFQT.d.ts} +3 -1
package/package.json +2 -1
package/plugins/acryl-door/src/host/channel.ts +124 -9
package/plugins/acryl-door/src/host/chat-tools.ts +8 -6
package/plugins/acryl-door/src/host/door-file.ts +7 -2
package/plugins/acryl-door/src/host/door.ts +58 -23
package/plugins/acryl-door/src/host/page-routes.ts +3 -1
package/plugins/acryl-door/src/host/page-socket.ts +18 -8
package/plugins/acryl-door/src/host/verbs.ts +3 -0
package/plugins/acryl-door/src/index.ts +166 -29
package/plugins/acryl-door/src/page/base.ts +32 -0
package/plugins/acryl-door/src/page/channel.ts +11 -1
package/plugins/acryl-door/src/page/driver/accessibility.ts +11 -0
package/plugins/acryl-door/src/page/driver/actions.ts +4 -0
package/plugins/acryl-door/src/page/driver/driver.ts +49 -7
package/plugins/acryl-door/src/page/driver/snapshot.ts +5 -2
package/plugins/acryl-door/src/page/index.ts +46 -2
package/plugins/acryl-door/src/page/indicator.ts +14 -6
package/plugins/acryl-door/src/page/outline.ts +56 -0
package/plugins/acryl-door/src/page/protocol.ts +4 -0
package/plugins/acryl-door/src/page/snapshot-text.ts +2 -1
package/plugins/acryl-node-server/src/adapter/listener.ts +4 -0
package/plugins/acryl-node-server/src/adapter/raw.ts +18 -0
package/plugins/acryl-node-server/src/adapter/websocket.ts +15 -9
package/plugins/acryl-node-server/src/client-modules.ts +7 -1
package/plugins/acryl-node-server/src/index.ts +304 -16
package/plugins/acryl-node-server/src/upgrade-hub.ts +2 -2
package/plugins/acryl-page/plugin.json +12 -0
package/plugins/acryl-page/src/index.ts +163 -0
package/plugins/acryl-router/src/service.ts +77 -14
package/plugins/acryl-router-http/src/index.ts +15 -1
package/plugins/acryl-router-http/src/serve.ts +31 -0
package/plugins/acryl-state/plugin.json +4 -3
package/plugins/acryl-state/src/client-source.ts +244 -0
package/plugins/acryl-state/src/service.ts +33 -6
package/plugins/acryl-state/src/socket.ts +96 -0
package/plugins/acryl-web-server/plugin.json +14 -0
package/plugins/acryl-web-server/src/index.ts +164 -0
package/plugins/agent/agent.ts +38 -7
package/plugins/agent/index.ts +1 -1
package/plugins/agent/model.ts +10 -2
package/plugins/agent/tools.ts +9 -3
package/plugins/agent-panel/client/describe.ts +57 -0
package/plugins/agent-panel/client/driver-pick.ts +22 -0
package/plugins/agent-panel/client/frame.ts +51 -0
package/plugins/agent-panel/client/main.ts +343 -81
package/plugins/agent-panel/drivers.ts +7 -2
package/plugins/agent-panel/headless.ts +5 -2
package/plugins/agent-panel/index.ts +187 -61
package/plugins/agent-panel/mount.ts +27 -0
package/plugins/agent-panel/visitors.ts +231 -0
package/plugins/desktop/frame.ts +231 -0
package/plugins/desktop/launch.ts +44 -9
package/plugins/desktop/main.ts +100 -32
package/plugins/desktop/window.ts +21 -4
package/plugins/driver-pty/client/terminal.ts +4 -1
package/plugins/driver-pty/index.ts +38 -11
package/plugins/driver-pty/spawn.ts +38 -0
package/plugins/driver-pty/terminal.ts +2 -0
package/plugins/extensions/index.ts +26 -1
package/plugins/extensions/resolve.ts +13 -0
package/plugins/feedback/client.d.ts +22 -0
package/plugins/feedback/client.js +471 -0
package/plugins/feedback/index.ts +143 -0
package/plugins/feedback/plugin.json +11 -0
package/plugins/feedback/store.ts +307 -0
package/plugins/home/index.ts +122 -0
package/plugins/home/plugin.json +11 -0
package/plugins/instance/index.ts +12 -3
package/plugins/manifest/app-plugins.ts +86 -0
package/plugins/manifest/index.ts +12 -2
package/plugins/manifest/snapshot.ts +275 -0
package/plugins/openai/index.ts +64 -5
package/plugins/openai/prompt.ts +23 -0
package/shared/AGENTS.core.md +36 -16
package/shared/skills/acryl-add-ui/SKILL.md +19 -0
package/shared/skills/acryl-app/SKILL.md +13 -0
package/shared/skills/acryl-build-plugin/SKILL.md +22 -0
package/shared/skills/acryl-change-plugin/SKILL.md +14 -0
package/shared/skills/acryl-diagnose-plugin/SKILL.md +13 -0
package/shared/skills/acryl-fix-plugin/SKILL.md +13 -0
package/shared/skills/acryl-remove-plugin/SKILL.md +12 -0
package/shared/skills/acryl-share-plugin/SKILL.md +16 -0
package/shared/skills/cordis-plugin/SKILL.md +26 -0
package/templates/agent/AGENTS.md +4 -2
package/templates/agent/blend.yaml +4 -0
package/templates/agent/gitignore +1 -0
package/templates/agent/package.json +1 -0
package/templates/agent/src/app.ts +150 -33
package/templates/agent/src/frame.ts +17 -0
package/templates/agent/src/main.ts +5 -3
package/templates/agent/src/routes.ts +73 -21
package/templates/agent/template.json +2 -0
package/templates/agent/test/app.test.ts +83 -5
package/templates/blank/AGENTS.md +3 -2
package/templates/blank/blend.yaml +11 -0
package/templates/blank/gitignore +1 -0
package/templates/blank/package.json +1 -0
package/templates/blank/src/app.ts +100 -29
package/templates/blank/src/door.ts +7 -0
package/templates/blank/src/first-page.ts +5 -0
package/templates/blank/src/frame.ts +17 -0
package/templates/blank/src/routes.ts +65 -8
package/templates/blank/template.json +14 -1
package/templates/blank/test/app.test.ts +103 -16
package/templates/chat/blend.yaml +2 -1
package/templates/chat/gitignore +1 -0
package/templates/chat/package.json +1 -0
package/templates/chat/src/app.ts +72 -22
package/templates/chat/src/chat-app.ts +11 -2
package/templates/chat/src/client/chat.tsx +4 -2
package/templates/chat/src/frame.ts +17 -0
package/templates/chat/src/main.ts +1 -6
package/templates/chat/src/page.tsx +6 -4
package/templates/chat/src/routes.ts +14 -4
package/templates/chat/src/runtime.ts +9 -3
package/templates/chat/template.json +3 -1
package/templates/chat/test/chat.test.ts +46 -1
package/templates/chat/test/server.test.ts +17 -3
package/templates/nodejs/blend.yaml +2 -1
package/templates/nodejs/gitignore +1 -0
package/templates/nodejs/package.json +1 -0
package/templates/nodejs/src/app.ts +76 -21
package/templates/nodejs/src/frame.ts +17 -0
package/templates/nodejs/src/main.ts +1 -6
package/templates/nodejs/src/page.tsx +3 -3
package/templates/nodejs/src/routes.ts +32 -13
package/templates/nodejs/template.json +3 -1
package/templates/nodejs/test/app.test.ts +38 -3
package/templates/nodejs/test/server.test.ts +17 -3
package/templates/notes/blend.yaml +2 -1
package/templates/notes/gitignore +1 -0
package/templates/notes/package.json +1 -0
package/templates/notes/src/app.ts +72 -22
package/templates/notes/src/frame.ts +17 -0
package/templates/notes/src/main.ts +1 -6
package/templates/notes/src/notes-app.ts +24 -17
package/templates/notes/src/routes.ts +11 -4
package/templates/notes/src/runtime.ts +9 -3
package/templates/notes/src/views.tsx +26 -17
package/templates/notes/template.json +3 -1
package/templates/notes/test/notes.test.ts +39 -1
package/templates/notes/test/server.test.ts +17 -3
package/templates/todo/blend.yaml +3 -0
package/templates/todo/gitignore +1 -0
package/templates/todo/package.json +1 -0
package/templates/todo/src/app.ts +81 -27
package/templates/todo/src/door.ts +7 -0
package/templates/todo/src/frame.ts +17 -0
package/templates/todo/src/page.ts +13 -6
package/templates/todo/src/todo.ts +18 -6
package/templates/todo/template.json +11 -1
package/templates/todo/test/todo.test.ts +67 -9
package/lib/src-LX0E4ec4.js +0 -117
package/shared/SKILL.md +0 -14

package/templates/notes/src/views.tsx CHANGED Viewed

@@ -11,13 +11,16 @@ if (filter) filter.addEventListener('input', () => {
 })
 `
+/** `base` is the path the app is mounted at: an empty string on its own server, `/app` when the ACRYL frame hosts it. Every URL here starts there. */
 const Layout = ({
   title,
   user,
+  base,
   children,
 }: {
   title: string
   user?: string
+  base: string
   children?: unknown
 }) => (
   <html lang="en">
@@ -37,23 +40,23 @@ const Layout = ({
         <strong>Notes</strong>
         {user ? (
           <>
-            <a href="/notes">All notes</a>
-            <a href="/notes/new">New note</a>
-            <form method="post" action="/logout">
+            <a href={`${base}/notes`}>All notes</a>
+            <a href={`${base}/notes/new`}>New note</a>
+            <form method="post" action={`${base}/logout`}>
               <span>{user} </span>
               <button type="submit">Log out</button>
             </form>
           </>
         ) : (
           <>
-            <a href="/login">Log in</a>
-            <a href="/signup">Sign up</a>
+            <a href={`${base}/login`}>Log in</a>
+            <a href={`${base}/signup`}>Sign up</a>
           </>
         )}
       </nav>
       {children}
       <script dangerouslySetInnerHTML={{ __html: counterScript }} />
-      <script type="module" src="/client/counter.tsx" />
+      <script type="module" src={`${base}/client/counter.tsx`} />
       {doorEnabled() ? <script type="module" src="/api/acryl-door/page.js" /> : null}
     </body>
   </html>
@@ -68,12 +71,17 @@ const Errors = ({ errors }: { errors: string[] }) =>
     </ul>
   ) : null
-export const authPage = (mode: 'login' | 'signup', errors: string[] = [], email = ''): string =>
+export const authPage = (
+  mode: 'login' | 'signup',
+  errors: string[] = [],
+  email = '',
+  base = '',
+): string =>
   (
-    <Layout title={mode === 'login' ? 'Log in' : 'Sign up'}>
+    <Layout title={mode === 'login' ? 'Log in' : 'Sign up'} base={base}>
       <h1>{mode === 'login' ? 'Log in' : 'Sign up'}</h1>
       <Errors errors={errors} />
-      <form method="post" action={`/${mode}`}>
+      <form method="post" action={`${base}/${mode}`}>
         <label for="email">Email</label>
         <input id="email" name="email" type="email" value={email} />
         <label for="password">Password</label>
@@ -85,11 +93,11 @@ export const authPage = (mode: 'login' | 'signup', errors: string[] = [], email
     </Layout>
   ).toString()
-export const listPage = (user: string, notes: Note[], q: string): string =>
+export const listPage = (user: string, notes: Note[], q: string, base = ''): string =>
   (
-    <Layout title="Notes" user={user}>
+    <Layout title="Notes" user={user} base={base}>
       <h1>Your notes</h1>
-      <form method="get" action="/notes">
+      <form method="get" action={`${base}/notes`}>
         <label for="filter">Search</label>
         <input id="filter" name="q" type="search" value={q} />
         <button type="submit">Search</button>
@@ -98,8 +106,8 @@ export const listPage = (user: string, notes: Note[], q: string): string =>
       <ul>
         {notes.map((n) => (
           <li data-note>
-            <a href={`/notes/${n.id}/edit`}>{n.title}</a>
-            <form method="post" action={`/notes/${n.id}/delete`} style="display:inline">
+            <a href={`${base}/notes/${n.id}/edit`}>{n.title}</a>
+            <form method="post" action={`${base}/notes/${n.id}/delete`} style="display:inline">
               <button type="submit">Delete</button>
             </form>
           </li>
@@ -113,12 +121,13 @@ export const formPage = (
   action: string,
   note: { title: string; body: string },
   errors: string[] = [],
+  base = '',
 ): string =>
   (
-    <Layout title="Note" user={user}>
+    <Layout title="Note" user={user} base={base}>
       <h1>{action === '/notes' ? 'New note' : 'Edit note'}</h1>
       <Errors errors={errors} />
-      <form method="post" action={action}>
+      <form method="post" action={`${base}${action}`}>
         <label for="title">Title</label>
         <input id="title" name="title" value={note.title} />
         <label for="body">Note</label>
@@ -127,7 +136,7 @@ export const formPage = (
         </textarea>
         <small id="count" aria-live="polite" data-island="counter" />
         <p>
-          <button type="submit">Save</button> <a href="/notes">Cancel</a>
+          <button type="submit">Save</button> <a href={`${base}/notes`}>Cancel</a>
         </p>
       </form>
     </Layout>

package/templates/notes/template.json CHANGED Viewed

@@ -7,6 +7,8 @@
     "manifest",
     "save",
     "extensions",
-    "acryl-door"
+    "acryl-door",
+    "acryl-web-server",
+    "acryl-page"
   ]
 }

package/templates/notes/test/notes.test.ts CHANGED Viewed

@@ -23,11 +23,12 @@ const projectRoot = fileURLToPath(new URL('..', import.meta.url))
  */
 const stops: (() => Promise<void>)[] = []
 after(() => Promise.all(stops.map((stop) => stop())))
-async function booted() {
+async function booted(options: { prefix?: string } = {}) {
   const home = await mkdtemp(join(scratch, 'notes-test-'))
   const app = await boot(withPort(pinnedInstance(home, { root: projectRoot }), 0), {
     database: join(home, 'test.sqlite'),
     listen: false,
+    ...options,
   })
   stops.push(async () => {
     await app.stop()
@@ -278,3 +279,40 @@ test('the note form loads the character counter, a client component compiled for
   assert.equal((await running.root.router.request('/client/@acrylblends/jsx-dom.js')).status, 200)
   assert.equal((await running.root.router.request('/client/../src/db.ts')).status, 404)
 })
+test('the frame mounts the app at /app: the login page, its links and redirects follow the prefix, and the client module is served there', async () => {
+  const running = await booted({ prefix: '/app' })
+  const root = running.root
+  const home = await root.router.request('/app')
+  assert.equal(home.status, 302)
+  assert.equal(home.headers.get('location'), '/app/notes')
+  const notes = await root.router.request('/app/notes')
+  assert.equal(notes.status, 302)
+  assert.equal(notes.headers.get('location'), '/app/login')
+  const login = await root.router.request('/app/login')
+  assert.equal(login.status, 200)
+  const loginHtml = await login.text()
+  assert.match(loginHtml, /action="\/app\/login"/u)
+  assert.match(loginHtml, /href="\/app\/signup"/u)
+  assert.match(loginHtml, /src="\/app\/client\/counter\.tsx"/u)
+  // Signing up through the framed path lands on the framed notes page, and its links stay under the prefix.
+  const signup = await root.router.request(
+    '/app/signup',
+    form({ email: 'framed@example.com', password: 'correct horse' }),
+  )
+  assert.equal(signup.status, 303)
+  assert.equal(signup.headers.get('location'), '/app/notes')
+  const cookie = (signup.headers.get('set-cookie') ?? '').split(';')[0] ?? ''
+  const list = await root.router.request('/app/notes', { headers: { cookie } })
+  assert.equal(list.status, 200)
+  const listHtml = await list.text()
+  assert.match(listHtml, /href="\/app\/notes\/new"/u)
+  assert.match(listHtml, /action="\/app\/notes"/u)
+  // The client component is compiled and served below the app's prefix.
+  const module = await root.router.request('/app/client/counter.tsx')
+  assert.equal(module.status, 200)
+  assert.match(module.headers.get('content-type') ?? '', /javascript/u)
+  assert.equal((await root.router.request('/app/client/@acrylblends/jsx-dom.js')).status, 200)
+  // The app's own URLs are not mounted in the frame; its own server keeps them (the tests above).
+  assert.equal((await root.router.request('/login')).status, 404)
+})

package/templates/notes/test/server.test.ts CHANGED Viewed

@@ -12,10 +12,24 @@ const scratch = join(fileURLToPath(new URL('..', import.meta.url)), '.acrylblend
 mkdirSync(scratch, { recursive: true })
 /** A sandbox may forbid listening on a port (Codex's workspace-write does); the tests that start the real server are skipped there, and every other test runs in process. */
+/**
+ * Whether this environment forbids listening at all: only a sandbox's refusal (EPERM/EACCES) means the real-server test must skip. A loaded
+ * machine can fail a bind transiently, so that is retried briefly; any other outcome lets the real test run, where a host that truly cannot
+ * listen fails loudly instead of hiding behind a skip.
+ */
 const canListen = await new Promise<boolean>((done) => {
-  const probe = createServer()
-  probe.once('error', () => done(false))
-  probe.listen(0, '127.0.0.1', () => probe.close(() => done(true)))
+  let attempts = 0
+  const probeOnce = (): void => {
+    attempts += 1
+    const probe = createServer()
+    probe.once('error', (error: NodeJS.ErrnoException) => {
+      if (error.code === 'EPERM' || error.code === 'EACCES') done(false)
+      else if (attempts < 3) setTimeout(probeOnce, 100)
+      else done(true)
+    })
+    probe.listen(0, '127.0.0.1', () => probe.close(() => done(true)))
+  }
+  probeOnce()
 })
 const skip = canListen ? false : 'this environment does not allow listening on a port'
 if (!canListen)

package/templates/todo/blend.yaml CHANGED Viewed

@@ -23,3 +23,6 @@ spec:
       name: acryl-node-server
       config:
         hostname: "{{parameters.hostname}}"
+    # The door: an agent working in this folder looks at the page and acts on it through .acryl/bin/acryl. Development only: src/app.ts leaves it out when NODE_ENV=production.
+    - id: acryl-door
+      name: acryl-door

package/templates/todo/gitignore CHANGED Viewed

@@ -1,3 +1,4 @@
 node_modules/
 .acrylblends/
 .acryl/
+package-lock.json

package/templates/todo/package.json CHANGED Viewed

@@ -16,6 +16,7 @@
     "test": "node --import ./plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
     "check": "tsc --noEmit",
     "lock": "node plugins/manifest/lock.ts",
+    "snapshot": "node plugins/manifest/snapshot.ts",
     "save": "node plugins/save/cli.ts",
     "upgrade": "node plugins/manifest/upgrade-cli.ts"
   },

package/templates/todo/src/app.ts CHANGED Viewed

@@ -1,30 +1,38 @@
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { Context, type Fiber } from '@deepseek-ai/cordis'
+import * as door from '../plugins/acryl-door/src/index.ts'
 import * as nodeServer from '../plugins/acryl-node-server/src/index.ts'
 import * as router from '../plugins/acryl-router/src/index.ts'
 import * as state from '../plugins/acryl-state/src/index.ts'
 import { type AppInstance, instance } from '../plugins/instance/index.ts'
 import {
+  appPluginNames,
   blueprintsIn,
   compose,
+  loadAppPlugins,
   loadManifest,
   type ParameterValue,
 } from '../plugins/manifest/index.ts'
+import { doorEnabled } from './door.ts'
 import * as todo from './todo.ts'
+import { FRAME_MOUNT_PREFIX } from './todo.ts'
-/** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them. */
+/** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them, and adds the app's own plugins from `plugins/` by name. */
 export const registry = {
   'acryl-router': router,
   'acryl-state': state,
   todo,
   'acryl-node-server': nodeServer,
+  'acryl-door': door,
 }
 export const APP_NAME = '__APP_NAME__'
 /** The manifest next to this app's source. */
 export const MANIFEST = join(fileURLToPath(new URL('..', import.meta.url)), 'blend.yaml')
+/** The app's plugins: the library copies `registry` imports, and the app's own plugins (a feature each), which `blend.yaml` mounts by their folder name. */
+const PLUGINS_DIR = join(fileURLToPath(new URL('..', import.meta.url)), 'plugins')
 /**
  * The app's manifest, resolved. A Blend finds its Blueprint in `blueprints/<id>.yaml`; an app that is itself a Blueprint never looks.
@@ -32,18 +40,21 @@ export const MANIFEST = join(fileURLToPath(new URL('..', import.meta.url)), 'ble
  */
 export function readManifest(values?: Readonly<Record<string, ParameterValue>>) {
   return loadManifest(MANIFEST, {
-    known: Object.keys(registry),
+    known: [...Object.keys(registry), ...appPluginNames(PLUGINS_DIR)],
     getBlueprint: blueprintsIn(join(fileURLToPath(new URL('..', import.meta.url)), 'blueprints')),
     ...(values ? { values } : {}),
   })
 }
-/** The manifest without its server row: the app is then reached in process, through `root.router.request`. */
-function withoutServer<M extends { plugins: readonly { use: string }[] }>(manifest: M): M {
+/** The manifest without some rows: without its server (and so its door) the app is reached in process, through `root.router.request`; the door is also left out in production. */
+function without<M extends { plugins: readonly { use: string }[] }>(
+  manifest: M,
+  ...uses: string[]
+): M {
   return {
     ...manifest,
     plugins: manifest.plugins.map((row) =>
-      row.use === 'acryl-node-server' ? { ...row, disabled: true } : row,
+      uses.includes(row.use) ? { ...row, disabled: true } : row,
     ),
   }
 }
@@ -55,32 +66,75 @@ export interface App {
   stop(): Promise<void>
 }
-/** The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. */
-export async function createApp(
+export interface AppOptions {
+  readonly values?: Readonly<Record<string, ParameterValue>>
+  /** The path the app is mounted at; absent on its own server, where it keeps `/todo`, and {@link FRAME_MOUNT_PREFIX} in the frame. */
+  readonly prefix?: string
+  /** Start the HTTP server (default). Tests pass `false` and call `app.root.router.request(path)`: it needs no port, so it also runs where a sandbox forbids listening. */
+  readonly listen?: boolean
+}
+/** The rows the frame host provides: the app contributes only the plugins that are its own. */
+const HOST_ROWS = [
+  'instance',
+  'acryl-router',
+  'acryl-node-server',
+  'acryl-web-server',
+  'acryl-page',
+  'manifest',
+  'save',
+  'acryl-door',
+]
+/**
+ * The app's rows, composed into `ctx`: the app's own server calls this from `createApp`, and the generated frame layer mounts it as one row, so the frame
+ * runs the app exactly as the app's own server does (same rows, same order, same config). `host: true` leaves the infrastructure rows to the frame host,
+ * which is where the door lives too, and mounts the app at {@link FRAME_MOUNT_PREFIX}.
+ */
+export async function composeInto(
+  ctx: Context,
   chosen: AppInstance,
-  options: {
-    values?: Readonly<Record<string, ParameterValue>>
-    /** Start the HTTP server (default). Tests pass `false` and call `app.root.router.request(path)`: it needs no port, so it also runs where a sandbox forbids listening. */
-    listen?: boolean
-  } = {},
-): Promise<App> {
-  const manifest = readManifest(options.values)
+  options: AppOptions & { readonly host?: boolean } = {},
+): Promise<Fiber[]> {
+  const read = readManifest(options.values)
+  const own = options.host !== true && options.listen !== false
+  // The frame host mounts the app under its own prefix; the app's own server keeps the app's old path.
+  const prefix = options.prefix ?? (options.host === true ? FRAME_MOUNT_PREFIX : undefined)
+  const leaveOut = new Set<string>(options.host === true ? HOST_ROWS : [])
+  // The server, and the door that needs it, are not mounted when the app is reached in process or inside the frame host.
+  if (!own) leaveOut.add('acryl-node-server').add('acryl-door')
+  if (!doorEnabled()) leaveOut.add('acryl-door')
+  const manifest = without(read, ...leaveOut)
+  // The rows that name one of the app's own plugin folders (a feature: plugins/<name>/ and its row) rather than a registry import; each one that runs is imported here.
+  const ownRows = [
+    ...new Set(read.plugins.map((row) => row.use).filter((use) => !Object.hasOwn(registry, use))),
+  ]
+  const ownPlugins = await loadAppPlugins(
+    PLUGINS_DIR,
+    ownRows.filter((use) => manifest.plugins.some((row) => row.use === use && !row.disabled)),
+  )
+  return compose(
+    ctx,
+    manifest,
+    { ...registry, ...ownPlugins },
+    {
+      // Runtime values the manifest cannot hold: where the list is kept (in the app's home) and, in the frame, the prefix the app answers at.
+      todo: {
+        file: join(chosen.home, 'todo.json'),
+        ...(prefix === undefined ? {} : { prefix }),
+      },
+      // Only the app's own server listens; the frame host owns the server and its port.
+      ...(own ? { server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 } } : {}),
+    },
+  )
+}
+/** The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. */
+export async function createApp(chosen: AppInstance, options: AppOptions = {}): Promise<App> {
   const root = new Context()
   const first = root.plugin(instance, chosen)
   await first.await()
-  const fibers: Fiber[] = [
-    first,
-    ...(await compose(
-      root,
-      options.listen === false ? withoutServer(manifest) : manifest,
-      registry,
-      {
-        // Runtime values the manifest cannot hold: where the list is kept (in the app's home) and where the server listens.
-        todo: { file: join(chosen.home, 'todo.json') },
-        server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 },
-      },
-    )),
-  ]
+  const fibers: Fiber[] = [first, ...(await composeInto(root, chosen, options))]
   return {
     root,
     url: options.listen === false ? '' : root.nodeServer.url,

package/templates/todo/src/door.ts ADDED Viewed

@@ -0,0 +1,7 @@
+/**
+ * The door (`plugins/acryl-door`) lets an agent working in this folder look at the running page and act on it, through `.acryl/bin/acryl`. It is on in development
+ * and off in production (`NODE_ENV=production`) and when `ACRYL_DOOR=off`: `src/app.ts` leaves its row out then, and the page leaves its script tag out. One process
+ * at a time serves a folder's door, so the tests that start the real server set `ACRYL_DOOR=off` and a second `npm start` beside a running one does not fail on it.
+ */
+export const doorEnabled = (): boolean =>
+  process.env.NODE_ENV !== 'production' && process.env.ACRYL_DOOR !== 'off'

package/templates/todo/src/frame.ts ADDED Viewed

@@ -0,0 +1,17 @@
+/**
+ * The app as the ACRYL frame hosts it (`npm run dev`): the generated layer mounts this row, which claims {@link FRAME_MOUNT_PREFIX} on the frame's web
+ * server. The app's own rows (the generated `app-plugins` row, which calls `composeInto`) mount the app at that prefix, so the page and its API answer at
+ * `/app`. Nothing here runs in production: `npm start` composes the app on its own server (no `routerHttp` service, so this row is not mounted there),
+ * where the app keeps `/todo`.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { FRAME_MOUNT_PREFIX } from './todo.ts'
+export const name = 'app-routes'
+/** The frame always has it: its layer carries the router and the web adapter. */
+export const inject = ['routerHttp']
+export function apply(ctx: Context): void {
+  ctx.routerHttp.mount(FRAME_MOUNT_PREFIX)
+}

package/templates/todo/src/page.ts CHANGED Viewed

@@ -1,26 +1,33 @@
-/** The page: plain HTML and a few lines of script; it follows the list through the server-sent event stream. */
-export const PAGE = `<!doctype html>
+import { doorEnabled } from './door.ts'
+/**
+ * The page: plain HTML and a few lines of script; it follows the list through the server-sent event stream. Every URL it writes is derived from
+ * `prefix`, the path the app is mounted at (`/todo` on its own server, `/app` when the ACRYL frame hosts it), so the same page works under both.
+ */
+export const pageHtml = (prefix: string): string => `<!doctype html>
 <meta charset="utf-8"><title>Todo</title>
 <style>body{font:16px system-ui;max-width:32rem;margin:2rem auto}ul{list-style:none;padding:0}li{display:flex;gap:.5rem;padding:.25rem 0}.done span{text-decoration:line-through;opacity:.6}</style>
 <h1>Todo</h1>
 <form id="add"><input id="title" placeholder="What needs doing?" autofocus> <button>Add</button></form>
 <ul id="list"></ul>
+${doorEnabled() ? '<script type="module" src="/api/acryl-door/page.js"></script>' : ''}
 <script>
+const base = ${JSON.stringify(prefix)}
 const list = document.getElementById('list')
 const send = (url, method, body) => fetch(url, { method, headers: { 'content-type': 'application/json' }, body: body && JSON.stringify(body) })
 document.getElementById('add').onsubmit = async event => {
   event.preventDefault()
   const input = document.getElementById('title')
-  await send('/todo/api', 'POST', { title: input.value })
+  await send(base + '/api', 'POST', { title: input.value })
   input.value = ''
 }
-new EventSource('/todo/events').onmessage = event => {
+new EventSource(base + '/events').onmessage = event => {
   list.replaceChildren(...JSON.parse(event.data).map(todo => {
     const item = document.createElement('li')
     item.className = todo.done ? 'done' : ''
-    const box = Object.assign(document.createElement('input'), { type: 'checkbox', checked: todo.done, onchange: () => send('/todo/api/' + todo.id, 'PATCH', { done: box.checked }) })
+    const box = Object.assign(document.createElement('input'), { type: 'checkbox', checked: todo.done, onchange: () => send(base + '/api/' + todo.id, 'PATCH', { done: box.checked }) })
     const title = document.createElement('span'); title.textContent = todo.title
-    const remove = Object.assign(document.createElement('button'), { textContent: 'x', onclick: () => send('/todo/api/' + todo.id, 'DELETE') })
+    const remove = Object.assign(document.createElement('button'), { textContent: 'x', onclick: () => send(base + '/api/' + todo.id, 'DELETE') })
     item.append(box, title, remove)
     return item
   }))

package/templates/todo/src/todo.ts CHANGED Viewed

@@ -10,14 +10,27 @@ import { Acryl, HTTPException } from '../plugins/acryl-router/src/index.ts'
 import { bodyLimit, loopbackOnly, trimTrailingSlash } from '../plugins/acryl-router/src/middleware/index.ts'
 import { schemaValidator, streamSSE, type StandardSchema } from '../plugins/acryl-router/src/helpers/index.ts'
 import type {} from '../plugins/acryl-state/src/index.ts'
-import { PAGE } from './page.ts'
+import { pageHtml } from './page.ts'
 /** Stable Cordis plugin name, equal to the package name and the Loader row id. */
 export const name = 'acryl-todo'
 export const inject = ['router', 'state']
+/**
+ * The only place the app's mount prefix is named: the app answers under `/todo` on its own server (`npm start`), and the ACRYL frame mounts the same app
+ * at `/app` (`npm run dev`). Every URL the page writes is derived from the prefix it is mounted at, so both are served by one source.
+ */
+export const FRAME_MOUNT_PREFIX = '/app'
 export interface Todo { id: number, title: string, done: boolean }
-export interface Config { file?: string }
+export interface Config {
+  file?: string
+  /**
+   * The path the app is mounted at, and the base of every URL its page writes. `/todo` on the app's own server (and the default); the ACRYL frame passes
+   * `/app` so the same app answers at the frame's app prefix, with nothing else of its URLs moved.
+   */
+  prefix?: string
+}
 /** Standard Schema for the body of a new todo, written by hand so the example has no schema library. */
 const NewTodo: StandardSchema<{ title: string }> = {
@@ -71,6 +84,7 @@ function save(file: string, todos: readonly Todo[]): void {
 }
 export function apply(ctx: Context, config: Config = {}): void {
+  const prefix = config.prefix ?? '/todo'
   const todos = ctx.state.cell<readonly Todo[]>('todo.list', load(config.file))
   if (config.file !== undefined) {
     const file = config.file
@@ -88,7 +102,7 @@ export function apply(ctx: Context, config: Config = {}): void {
   // so the page is found either way while each route keeps one canonical path (the router itself treats `/a` and `/a/` as different).
   const api = new Acryl()
     .use(loopbackOnly({ inProcess: 'allow' }), bodyLimit({ maxSize: MAX_BODY_BYTES }), trimTrailingSlash())
-    .get('/', c => c.html(PAGE))
+    .get('/', c => c.html(pageHtml(prefix)))
     .get('/api', c => c.json(todos.get()))
     .post('/api', schemaValidator('json', NewTodo), c => {
       const todo: Todo = { id: nextId(), title: c.req.valid('json').title, done: false }
@@ -119,7 +133,5 @@ export function apply(ctx: Context, config: Config = {}): void {
         unsubscribe()
       }
     }))
-  ctx.router.route('/todo', api)
-  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/todo') })
+  ctx.router.route(prefix === '' ? '/' : prefix, api)
 }

package/templates/todo/template.json CHANGED Viewed

@@ -1,4 +1,14 @@
 {
-  "plugins": ["instance", "acryl-router", "acryl-state", "acryl-node-server", "manifest", "save"],
+  "plugins": [
+    "instance",
+    "acryl-router",
+    "acryl-state",
+    "acryl-node-server",
+    "manifest",
+    "save",
+    "acryl-door",
+    "acryl-web-server",
+    "acryl-page"
+  ],
   "desktopPath": "/todo"
 }

package/templates/todo/test/todo.test.ts CHANGED Viewed

@@ -7,6 +7,7 @@ import { test } from 'node:test'
 import { fileURLToPath } from 'node:url'
 import { pinnedInstance, withPort } from '../plugins/instance/index.ts'
 import { type App, createApp, readManifest } from '../src/app.ts'
+import { FRAME_MOUNT_PREFIX } from '../src/todo.ts'
 /** Throwaway homes live inside the project (`.acrylblends/` is ignored by git): a sandboxed agent may not write to the system temp folder. */
 const scratch = join(fileURLToPath(new URL('..', import.meta.url)), '.acrylblends', 'test')
@@ -14,9 +15,16 @@ mkdirSync(scratch, { recursive: true })
 const projectRoot = fileURLToPath(new URL('..', import.meta.url))
-/** Boot the app with its data in `home`, run the test, always stop it. In process by default (`app.root.router.request`); `listen` starts the real server on any free port. */
-async function withApp(home: string, run: (app: App) => Promise<void>, listen = false) {
-  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0), { listen })
+/** Boot the app with its data in `home`, run the test, always stop it. In process by default (`app.root.router.request`); `listen` starts the real server on any free port; `prefix` mounts it where the frame does. */
+async function withApp(
+  home: string,
+  run: (app: App) => Promise<void>,
+  options: { listen?: boolean; prefix?: string } = {},
+) {
+  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0), {
+    listen: false,
+    ...options,
+  })
   try {
     await run(app)
   } finally {
@@ -59,10 +67,24 @@ test('creates, completes, lists and deletes', () =>
   ))
 /** A sandbox may forbid listening on a port (Codex's workspace-write does). The one test that needs a real connection (the origin check looks at who connected) is skipped there, and says so. */
+/**
+ * Whether this environment forbids listening at all: only a sandbox's refusal (EPERM/EACCES) means the real-server test must skip. A loaded
+ * machine can fail a bind transiently, so that is retried briefly; any other outcome lets the real test run, where a host that truly cannot
+ * listen fails loudly instead of hiding behind a skip.
+ */
 const canListen = await new Promise<boolean>((done) => {
-  const probe = createServer()
-  probe.once('error', () => done(false))
-  probe.listen(0, '127.0.0.1', () => probe.close(() => done(true)))
+  let attempts = 0
+  const probeOnce = (): void => {
+    attempts += 1
+    const probe = createServer()
+    probe.once('error', (error: NodeJS.ErrnoException) => {
+      if (error.code === 'EPERM' || error.code === 'EACCES') done(false)
+      else if (attempts < 3) setTimeout(probeOnce, 100)
+      else done(true)
+    })
+    probe.listen(0, '127.0.0.1', () => probe.close(() => done(true)))
+  }
+  probeOnce()
 })
 const skip = canListen ? false : 'this environment does not allow listening on a port'
 if (!canListen)
@@ -89,7 +111,7 @@ test(
           assert.equal((await post({})).status, 201)
           assert.equal((await post({ origin: new URL(app.url).origin })).status, 201)
         },
-        true,
+        { listen: true },
       ),
     ),
 )
@@ -162,9 +184,45 @@ test('serves the page, and streams the list: now, and again on every change', ()
     }),
   ))
+test('the frame mounts the same app at /app; the app on its own server keeps /todo', () =>
+  withHome((home) =>
+    withApp(
+      home,
+      async (app) => {
+        // The frame row claims the app's prefix on the host's web server; the app's own rows mount it there.
+        const frame = await import('../src/frame.ts')
+        assert.deepEqual([...frame.inject].sort(), ['routerHttp'])
+        assert.equal(FRAME_MOUNT_PREFIX, '/app')
+        const page = await app.root.router.request(FRAME_MOUNT_PREFIX)
+        assert.equal(page.status, 200)
+        const html = await page.text()
+        assert.match(html, /<title>Todo<\/title>/)
+        // The page writes every URL from the prefix it is mounted at.
+        assert.match(html, new RegExp(`const base = "${FRAME_MOUNT_PREFIX}"`, 'u'))
+        assert.deepEqual(await (await send(app, 'GET', `${FRAME_MOUNT_PREFIX}/api`)).json(), [])
+        const created = await send(app, 'POST', `${FRAME_MOUNT_PREFIX}/api`, { title: 'framed' })
+        assert.equal(created.status, 201)
+        const list = (await (await send(app, 'GET', `${FRAME_MOUNT_PREFIX}/api`)).json()) as Array<{
+          title: string
+        }>
+        assert.deepEqual(
+          list.map((todo) => todo.title),
+          ['framed'],
+        )
+        // The standalone URLs did not move: the app still answers under /todo on its own server.
+        assert.equal((await send(app, 'GET', '/todo')).status, 404)
+      },
+      { prefix: FRAME_MOUNT_PREFIX },
+    ),
+  ))
 test('the manifest decides what is mounted', () => {
+  // The template's rows, in their order; a feature's row (plugins/<name>/) may sit between them.
+  const library = ['router', 'state', 'todo', 'server', 'acryl-door']
   assert.deepEqual(
-    readManifest().plugins.map((row) => row.id),
-    ['router', 'state', 'todo', 'server'],
+    readManifest()
+      .plugins.map((row) => row.id)
+      .filter((id) => library.includes(id)),
+    library,
   )
 })