acrylblends 1.1.0 → 1.3.0

package/plugins/extensions/index.ts

@@ -31,8 +31,8 @@ import { type Context, type Fiber, Service } from '@deepseek-ai/cordis'
 import type {} from '../instance/index.ts'
 import type { Sandbox } from '../sandbox/index.ts'
 import { appendLedger, type LedgerEntry, readLedger } from './ledger.ts'
-import { resolveFromApp, routerAliases } from './resolve.ts'
-import { discard, hashFolder, prune, stage } from './stage.ts'
+import { type PluginStore, pluginVersion } from './plugin-store.ts'
+import { folderPluginStore } from './stage.ts'
 
 /** A fiber's lifecycle state, by name (Cordis's own enum is a `const enum`, which does not exist at run time). */
 export type ExtensionState = 'pending' | 'loading' | 'active' | 'failed' | 'disposed' | 'unloading'
@@ -83,6 +83,16 @@ export interface ExtensionsConfig {
   readOnly?: boolean
   /** Where the read-only start says what it did (the console by default). */
   log?: (line: string) => void
+  /**
+   * Plugins of the sources that are switched off (Settings → Plugins writes this list into `blend.yaml`): they are not started, in development or
+   * production, until taken off the list. Their folders stay as they are.
+   */
+  off?: readonly string[]
+  /**
+   * Plugins of the sources that `blend.yaml` mounts as rows of their own (the app composes them in its row order, with their row's config): they
+   * are not extensions, so they are neither found nor started here, and installing one is refused with that reason.
+   */
+  rows?: readonly string[]
 }
 
 const READ_ONLY =
@@ -214,7 +224,6 @@ interface StateService {
 
 export class Extensions extends Service {
   readonly sources: readonly ExtensionSource[]
-  readonly stageRoot: string
   readonly stateFile: string
   readonly ledgerFile: string
   /** Settles when the startup pass is done. */
@@ -227,17 +236,23 @@ export class Extensions extends Service {
   private tail: Promise<unknown> = Promise.resolve()
   private disposed = false
   private readonly readOnly: boolean
+  private readonly off: ReadonlySet<string>
+  private readonly rows: ReadonlySet<string>
   private readonly say: (line: string) => void
   /**
    * The context the service was constructed with. Inside a service method `this.ctx` is Cordis's shadow context, which resolves services as the
    * service's own fiber, so a plugin mounted from it would read `ctx.router` from the installer's fiber and fail. Extensions mount from this one.
    */
   private readonly owner: Context
+  private readonly store: PluginStore
 
-  constructor(ctx: Context, config: ExtensionsConfig = {}) {
+  constructor(ctx: Context, config: ExtensionsConfig, store: PluginStore) {
     super(ctx, 'extensions')
     this.owner = ctx
+    this.store = store
     this.readOnly = config.readOnly === true
+    this.off = new Set(config.off ?? [])
+    this.rows = new Set(config.rows ?? [])
     this.say = config.log ?? ((line) => console.log(line))
     const { home, root } = ctx.appInstance
     this.sources = (config.sources ?? [{ dir: join(home, 'extensions'), trust: 'install' }]).map(
@@ -246,20 +261,20 @@ export class Extensions extends Service {
         trust: config.approval === true && source.trust === 'install' ? 'ask' : source.trust,
       }),
     )
-    this.stageRoot = join(home, 'extensions-staged')
     this.stateFile = join(home, 'extensions.json')
     this.ledgerFile = join(home, 'extensions-ledger.jsonl')
     // Effects run their disposers newest first: settle pending operations, then dispose every mounted extension, then drop the hook.
     // Staged copies live in the app's home, outside the app: their bare imports are resolved from the app. A read-only start imports the folders where they are (inside the app).
     if (!this.readOnly)
       ctx.effect(
-        () => resolveFromApp(this.stageRoot, root, routerAliases()),
+        () => this.store.resolveImportsFrom(root),
         'extensions: resolve staged imports from the app',
       )
     ctx.effect(
       () => async () => {
+        // A fiber already being disposed (an app reload) can return nothing here, not a promise.
         for (const entry of [...this.installed.values()].reverse())
-          await entry.fiber.dispose().catch(() => undefined)
+          await Promise.resolve(entry.fiber.dispose()).catch(() => undefined)
         this.installed.clear()
       },
       'extensions: dispose mounted extensions',
@@ -302,7 +317,7 @@ export class Extensions extends Service {
           this.stale.add(entry.name)
           continue
         }
-        if (hashFolder(entry.source) !== entry.version)
+        if (pluginVersion(entry.source) !== entry.version)
           results.push(await this.installNow(entry.source))
       }
       for (const found of this.discover()) {
@@ -350,7 +365,7 @@ export class Extensions extends Service {
         }
       }
       this.requests.delete(name)
-      if (!existsSync(request.dir) || hashFolder(request.dir) !== request.version) {
+      if (!existsSync(request.dir) || pluginVersion(request.dir) !== request.version) {
         return {
           ok: false,
           stage: 'approval',
@@ -417,6 +432,8 @@ export class Extensions extends Service {
           entry.isDirectory() &&
           NAME.test(entry.name) &&
           !library.has(entry.name) &&
+          !this.off.has(entry.name) &&
+          !this.rows.has(entry.name) &&
           ENTRIES.some((file) => existsSync(join(dir, file)))
         ) {
           if (!found.some((other) => other.name === entry.name))
@@ -442,6 +459,10 @@ export class Extensions extends Service {
       errors.push(
         `the folder name "${name}" must be lowercase letters, digits and dashes; it is the extension's name`,
       )
+    if (this.rows.has(name))
+      errors.push(
+        `"${name}" is a row of blend.yaml, so the app starts it, in its row order and with its row's config; it is not installed here. Change its folder and the running app loads it again (npm run dev); npm test checks it`,
+      )
     if (!existsSync(dir) || !statSync(dir).isDirectory()) errors.push(`"${dir}" is not a folder`)
     else if (!ENTRIES.some((file) => existsSync(join(dir, file))))
       errors.push(`"${dir}" has no ${ENTRIES.join(', ')}`)
@@ -596,7 +617,7 @@ export class Extensions extends Service {
     const { name, dir, errors } = this.check(source)
     if (errors.length > 0) return { ok: false, stage: 'check', name, errors, next: NOTHING }
     const previous = this.installed.get(name)
-    const version = hashFolder(dir)
+    const version = pluginVersion(dir)
     const running =
       previous && previous.version === version && STATES[previous.fiber.state] !== 'failed'
     // A source that asks: this exact version must have been approved. Anything else waits, and the ledger says so.
@@ -627,12 +648,12 @@ export class Extensions extends Service {
     }
 
     // Import the new version while the old one keeps running: a syntax error or a missing export changes nothing.
-    const staged = stage(dir, this.stageRoot, name)
+    const staged = this.store.put(name, dir)
     let module: PluginModule
     try {
       module = await this.load(staged.dir, name)
     } catch (error) {
-      discard(staged.dir)
+      this.store.discard(staged)
       this.record({ kind: 'refused', name, version: staged.version, error: message(error) })
       return {
         ok: false,
@@ -659,7 +680,7 @@ export class Extensions extends Service {
           : undefined
     if (failure) {
       await mounted.fiber.dispose().catch(() => undefined)
-      discard(staged.dir)
+      this.store.discard(staged)
       const error = failure.error
       this.record({ kind: 'refused', name, version: staged.version, error })
       let restored = false
@@ -696,7 +717,7 @@ export class Extensions extends Service {
     })
     this.stale.delete(name)
     this.saveState()
-    prune(this.stageRoot, name, [staged.dir])
+    this.store.keepOnly(name, staged)
     this.record({ kind: action, name, version: staged.version })
     this.ctx.emit('extensions/changed', name, action)
     return {
@@ -716,7 +737,7 @@ export class Extensions extends Service {
     this.installed.delete(name)
     this.stale.delete(name)
     this.saveState()
-    prune(this.stageRoot, name, [])
+    this.store.keepOnly(name)
     this.record({ kind: 'removed', name, version: entry.version })
     this.ctx.emit('extensions/changed', name, 'removed')
     return { ok: true, name }
@@ -741,7 +762,7 @@ export class Extensions extends Service {
         this.installed.set(folder.name, {
           name: folder.name,
           source: folder.dir,
-          version: hashFolder(folder.dir),
+          version: pluginVersion(folder.dir),
           dir: folder.dir,
           module,
           fiber: mounted.fiber,
@@ -788,6 +809,10 @@ export class Extensions extends Service {
       summary.failed.push({ name: 'extensions.json', error: message(error) })
     }
     for (const [name, record] of Object.entries(records)) {
+      // Switched off: not started, and dropped from the record; switched on again, its folder is found and installed as new.
+      if (this.off.has(name)) continue
+      // Now a row of blend.yaml: the app starts it, and the record of its install is dropped.
+      if (this.rows.has(name)) continue
       try {
         // What was installed before was approved then: an unchanged source starts again without asking.
         this.approved.set(name, record.version)
@@ -800,7 +825,7 @@ export class Extensions extends Service {
         // The source is gone: the last installed version still runs, and is reported as stale.
         summary.stale.push(name)
         this.stale.add(name)
-        if (!existsSync(record.dir)) {
+        if (!this.store.holds(record)) {
           summary.failed.push({ name, error: 'neither the source nor the staged copy exists' })
           continue
         }
@@ -844,7 +869,11 @@ export const extensions = {
   name: 'extensions',
   inject: ['appInstance'],
   async apply(ctx: Context, config: ExtensionsConfig) {
-    const service = new Extensions(ctx, config ?? {})
+    const service = new Extensions(
+      ctx,
+      config ?? {},
+      folderPluginStore(join(ctx.appInstance.home, 'extensions-staged')),
+    )
     await service.ready
   },
 }

package/plugins/extensions/plugin-store.ts

@@ -0,0 +1,27 @@
+/**
+ * Where installed versions of a plugin are kept, as the install transaction needs it. The transaction (`index.ts`) owns this port and says nothing about folders,
+ * copies or URLs; `stage.ts` is the adapter that keeps them on disk (Clean Architecture: a boundary owned by the use case; the layout is a detail).
+ */
+import { digestFolder } from '@webboxes/blends-core'
+
+/** One kept version of a plugin. `dir` is what the transaction imports it from. */
+export interface StoredPlugin {
+  readonly dir: string
+  readonly version: string
+}
+
+export interface PluginStore {
+  /** Keep this source as a version of `name` and return it. An unchanged source returns the version already kept. */
+  put(name: string, source: string): StoredPlugin
+  /** Whether this version, recorded earlier, is still here. */
+  holds(plugin: StoredPlugin): boolean
+  /** Drop a version that was refused. */
+  discard(plugin: StoredPlugin): void
+  /** Drop every version of `name` but `plugin`; all of them when none is given. */
+  keepOnly(name: string, plugin?: StoredPlugin): void
+  /** Let kept plugins import what the app at `appRoot` provides, until the returned function is called. */
+  resolveImportsFrom(appRoot: string): () => void
+}
+
+/** A short content digest of a plugin's folder: an unchanged source keeps its version. */
+export const pluginVersion = (dir: string): string => digestFolder(dir, 12)

package/plugins/extensions/plugin.json

@@ -6,7 +6,7 @@
   "provides": ["extensions"],
   "dependencies": {
     "@deepseek-ai/cordis": "4.0.4",
-    "@webboxes/blends-core": "0.4.0"
+    "@webboxes/blends-core": "0.5.0"
   },
   "mount": "mount it after instance: root.plugin(extensions, { sources: [{ dir: join(root, 'plugins'), trust: 'install' }] })"
 }

package/plugins/extensions/resolve.ts

@@ -101,6 +101,19 @@ export function routerAliases(): Record<string, string> {
     // outside the app folder, where Node would not find that entry.
     aliases[folder.name] ??= entry
     aliases[`#${folder.name}`] = entry
+    // Its other top-level modules by subpath, as its package exports them (`acryl-node-server/client-modules`): the door imports one before any extension is installed.
+    for (const file of readdirSync(fileURLToPath(new URL(`${folder.name}/src/`, plugins)))) {
+      if (
+        !file.endsWith('.ts') ||
+        file === 'index.ts' ||
+        file.endsWith('.test.ts') ||
+        file.endsWith('.d.ts')
+      )
+        continue
+      aliases[`${folder.name}/${file.slice(0, -3)}`] ??= fileURLToPath(
+        new URL(`${folder.name}/src/${file}`, plugins),
+      )
+    }
     const suite = fileURLToPath(new URL(`${folder.name}/src/conformance.ts`, plugins))
     if (existsSync(suite)) aliases[`#${folder.name}/conformance`] = suite
   }

package/plugins/extensions/stage.ts

@@ -7,10 +7,9 @@
  */
 import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from 'node:fs'
 import { basename, join } from 'node:path'
-import { digestFolder, FOLDER_DIGEST_SKIPPED } from '@webboxes/blends-core'
-
-/** A short content digest of a folder, so an unchanged source keeps its version. */
-export const hashFolder = (dir: string, length = 12): string => digestFolder(dir, length)
+import { FOLDER_DIGEST_SKIPPED } from '@webboxes/blends-core'
+import { type PluginStore, pluginVersion } from './plugin-store.ts'
+import { resolveFromApp, routerAliases } from './resolve.ts'
 
 /**
  * Whether `node --watch` runs this process. It watches every module the process has imported, and keeps watching the paths of the runs before; a staged copy that is deleted
@@ -40,7 +39,7 @@ export function stage(
   stageRoot: string,
   name: string,
 ): { dir: string; version: string } {
-  const version = hashFolder(source)
+  const version = pluginVersion(source)
   const existing = staged(stageRoot, name, version)
   if (existing !== undefined) return { dir: existing, version }
   const stamp = String(Date.now()).padStart(15, '0')
@@ -70,3 +69,14 @@ export function prune(stageRoot: string, name: string, keep: readonly string[]):
     if (!keep.includes(path)) rmSync(path, { recursive: true, force: true })
   }
 }
+
+/** The plugin store of an app: its versions as staged copies under `stageRoot`. */
+export function folderPluginStore(stageRoot: string): PluginStore {
+  return {
+    put: (name, source) => stage(source, stageRoot, name),
+    holds: ({ dir }) => existsSync(dir),
+    discard: ({ dir }) => discard(dir),
+    keepOnly: (name, plugin) => prune(stageRoot, name, plugin ? [plugin.dir] : []),
+    resolveImportsFrom: (appRoot) => resolveFromApp(stageRoot, appRoot, routerAliases()),
+  }
+}

package/plugins/feedback/client.d.ts

@@ -0,0 +1,22 @@
+// Types for the browser client served as-is (client.js): the Host reads it as text and appends its start call; tests import the exported helpers.
+
+/** The ACRYL frame's view handle, or undefined when the page is not in the frame's canvas. */
+export function frameViewOf(win: {
+  readonly parent: unknown
+}): { readonly mode: 'build' | 'preview' } | undefined
+
+/** A short name for a picked element: what it says it is, else its heading, else the first words it shows, else its tag. */
+export function elementLabel(element: Element): string
+
+/** The stored size of a screenshot: the whole view, downscaled to `maxSide`. */
+export function shotSize(
+  width: number,
+  height: number,
+  maxSide?: number,
+): { width: number; height: number }
+
+/** The largest screenshot the page sends (decoded bytes); the Host refuses more than 512 KB. */
+export const SHOT_MAX_BYTES: number
+
+/** Whether this browser can capture the current tab (Chromium only; Firefox and Safari would offer the whole screen). */
+export function canCaptureTab(userAgent: string, hasDisplayCapture: boolean): boolean