@abide/abide 0.101.0 → 0.102.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.101.0",
+    "version": "0.102.0",
     "type": "module",
     "description": "Isomorphic type-safe framework for reactive async interfaces for humans and machines",
     "license": "MIT",
@@ -25,7 +25,7 @@
         "cli"
     ],
     "engines": {
-        "bun": ">=1.3.0"
+        "bun": ">=1.4.3"
     },
     "publishConfig": {
         "access": "public",
@@ -62,12 +62,14 @@
         "typescript": "^7.0.2"
     },
     "scripts": {
-        "typecheck": "tsc -p tsconfig.json"
+        "typecheck": "bun check",
+        "prepack": "bun ../../scripts/packDocs.ts"
     },
     "files": [
         "src",
         "bin",
         "scaffold",
+        "docs",
         "CHANGELOG.md"
     ]
 }

package/scaffold/AGENTS.md

@@ -0,0 +1,31 @@
+# Working on this app
+
+This is an abide app. abide is newer than any model's training data, so read its documentation
+before writing code, rather than guessing from Svelte, Vue or React. It installs with the package:
+
+- `node_modules/@abide/abide/docs/abide.md` — every documentation page in reading order, with a
+  working example for each task. It is long: read its Contents, then search for the page's
+  address, which heads each page as a comment — `<!-- values/show-a-value-that-changes.md -->`.
+- `node_modules/@abide/abide/docs/REGISTRY.md` — every name an app can import or write, with its
+  signature and the rules that govern it.
+- `node_modules/@abide/abide/docs/RULEBOOK.md` — every rule, numbered. A compiler or server
+  message that ends in `RULEBOOK 23.16.` names a clause in this file — search it for `23.16`.
+
+## Checking your work
+
+- `bun run check` — runs `abide check`, the type checker over `.abide` files. `tsc` and an editor's
+  TypeScript service do not read `.abide` files, so a clean `tsc` says nothing about them. Run
+  `bun run check` after every change, and treat its warnings as bugs: several of them name a read
+  that will not update when its value changes.
+- `bun run dev` — serves the app on a local port and rebuilds when a file changes.
+- `bun run build` then `bun run start` — the production build, and the app served from it.
+
+## Layout
+
+- Every directory under `src/` is an address: `src/invoices/page.abide` answers `/invoices`.
+  `layout.abide` wraps the pages below it, and the outermost one writes `<html>`.
+- A module under a `server` directory runs on the server only, and importing one from browser
+  code is a compile error. A file under a `public` directory is served as it is:
+  `src/blog/public/cover.png` answers `/blog/cover.png`.
+- Handlers and hooks go in a `<script server>` block of a `.abide` file.
+- Import the app's own modules as `#src/…` (see `imports` in `package.json`).

package/scaffold/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/scaffold/src/layout.abide

@@ -0,0 +1,18 @@
+<script server>
+import { log, onStart } from '@abide/abide/server'
+
+onStart(async (start) => {
+    await start()
+    log('started')
+})
+</script>
+
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+</head>
+<body>
+    <slot/>
+</body>
+</html>

package/src/compiler/Lowering.ts

@@ -42,6 +42,9 @@ const SHORT_CIRCUIT: ReadonlySet<string> = new Set(['||', '&&', '??'])
  * so the import goes with the call; left to the callers it is one `used.add` per call site and a
  * missed one emits a module calling a name it never imported.
  */
+/** A run of emitted code a `Lowering` wrote, and where each of its runs stood in the projection. */
+export type LoweredChunk = { text: string; origins: Origin[] }
+
 export class Lowering {
     readonly projection: Projection
     readonly used = new Set<string>()
@@ -77,12 +80,23 @@ export class Lowering {
      * still checked.
      */
     readonly refusals: Finding[] = []
-
-    constructor(file: AbideFile, answer: CheckerAnswer, checking = false) {
+    /**
+     * 38.97 — where given, each chunk this lowering hands an emitter, with where its runs stood in
+     * the projection: what `sourceMapOf` finds in the module the emitter writes.
+     */
+    private readonly chunks: LoweredChunk[] | undefined
+
+    constructor(
+        file: AbideFile,
+        answer: CheckerAnswer,
+        checking = false,
+        chunks?: LoweredChunk[],
+    ) {
         this.projection = projectShadow(file)
         this.answer = answer
         this.holdsSlot = holdsSlot(file.template)
         this.checking = checking
+        this.chunks = chunks
     }
 
     /**
@@ -160,17 +174,22 @@ export class Lowering {
 
     /** The `<script module>` blocks, joined as the file wrote them and lowered. */
     modules(): string {
-        return this.lower(this.projection.modules)
+        return this.lowerChunk(this.projection.modules)
+    }
+
+    /** The `<script server>` blocks, joined as the file wrote them and lowered. */
+    servers(): string {
+        return this.lowerChunk(this.projection.servers)
     }
 
     /** The `<script>` blocks, joined as the file wrote them and lowered. */
     scripts(): string {
-        return this.lower(this.projection.scripts)
+        return this.lowerChunk(this.projection.scripts)
     }
 
     /** A template expression, lowered. */
     expression(holder: object): string {
-        return grouped(this.lower(this.spanOf(holder)))
+        return grouped(this.lowerChunk(this.spanOf(holder)))
     }
 
     /**
@@ -180,7 +199,7 @@ export class Lowering {
      * lowers to its own record as a file's does to the file's.
      */
     setup(holder: Setup | InlineComponent): string {
-        return this.lower(this.spanOf(holder))
+        return this.lowerChunk(this.spanOf(holder))
     }
 
     /**
@@ -196,7 +215,36 @@ export class Lowering {
      * passed through.
      */
     reference(holder: object): string {
-        return grouped(this.lower(this.spanOf(holder), true))
+        const span = this.spanOf(holder)
+        return this.boundPath(span) ?? grouped(this.lowerChunk(span, true))
+    }
+
+    /**
+     * 32.5, 31.8 — A `bind:` OPERAND THAT IS A PATH INTO A VALUE, `contact.address.city`, as the
+     * `{ get, set }` pair a binding writes through: the read for its get, and the write 31.8 lowers
+     * `contact.address.city = v` to for its set. Lowered as a read, the binding was handed the city
+     * as a string and had nothing to write the typed text back into.
+     *
+     * A STATIC PATH ONLY — names and dots, which carry no read of their own. `undefined` for any
+     * other operand, which `reference` lowers as it stands.
+     */
+    private boundPath(span: Span): string | undefined {
+        if (this.checking) return undefined
+        const source = this.projection.text
+        const text = source.slice(span.start, span.end)
+        const from = span.start + (text.length - text.trimStart().length)
+        const to = span.start + text.trimEnd().length
+        const reads = this.answer.reads
+        const read = reads[this.answer.firstRead(from)]
+        if (read === undefined || read.from !== from || read.shape !== 'value')
+            return undefined
+        const path = source.slice(read.to, to)
+        if (!/^(\s*\.\s*[A-Za-z_$][\w$]*)+$/.test(path)) return undefined
+        const name = this.nameOf(read)
+        const segments: string[] = []
+        for (const [, segment] of path.matchAll(/\.\s*([A-Za-z_$][\w$]*)/g))
+            segments.push(JSON.stringify(segment))
+        return `{ get: () => ${this.lowerChunk({ start: from, end: to })}, set: (${STORED}) => ${name}.set(${this.use('writePath')}(${name}(), [${segments.join(', ')}], ${STORED})) }`
     }
 
     /**
@@ -209,7 +257,7 @@ export class Lowering {
     chosenTag(node: object): string | undefined {
         const span = this.projection.tags.get(node)
         if (span === undefined || !this.answer.holdsRead(span)) return undefined
-        return this.lower(span)
+        return this.lowerChunk(span)
     }
 
     /** A `{#for}` block's key expression, lowered. */
@@ -217,7 +265,7 @@ export class Lowering {
         const span = this.projection.keys.get(block)
         if (span === undefined)
             throw new Error('abide: a {#for} key was never projected.')
-        return grouped(this.lower(span))
+        return grouped(this.lowerChunk(span))
     }
 
     /**
@@ -283,6 +331,15 @@ export class Lowering {
         return span
     }
 
+    /** `lower`, the chunk recorded where `chunks` was given. */
+    private lowerChunk(span: Span, holds = false): string {
+        if (this.chunks === undefined) return this.lower(span, holds)
+        const origins: Origin[] = []
+        const text = this.lower(span, holds, origins)
+        this.chunks.push({ text, origins })
+        return text
+    }
+
     /**
      * The source of `span`, every read in it rewritten.
      *
@@ -484,6 +541,11 @@ export class Lowering {
             // the call (`expressionFacts`), so a `<script>`'s `raw` stays the file's.
             case 'raw':
                 return this.use('raw')
+            // 27.13 — the call bound to a name, for the checker to read the defaults' type off.
+            case 'config':
+                return this.checking
+                    ? `const ${CHECKED_CONFIG}${read.start} = ${CHECKED_CONFIG_OF}(${spelled})`
+                    : undefined
         }
         const value =
             read.value === undefined ? '1' : this.lower(read.value).trim()
@@ -611,6 +673,13 @@ export const PROPS = '__props'
 /** The record a checked lowering reads each value through (`Lowering.values`). */
 export const CHECKED_VALUES = '__values'
 
+/**
+ * 27.13 — what a checked lowering binds an `onConfig(…)` statement to, suffixed by where the call
+ * stands, and the declared function that hands that call back typed as what its defaults return.
+ */
+export const CHECKED_CONFIG = '__config'
+export const CHECKED_CONFIG_OF = '__configOf'
+
 /**
  * The checked lowering's write guard: holds a written value to what `set` takes.
  *

package/src/compiler/ShadowMap.ts

@@ -3,7 +3,7 @@ import type { Origin, Span } from './projectShadow.ts'
 /** What a `.abide`'s checked module is registered with the checker as, beside the `.abide`. */
 export const CHECKED_SUFFIX = '.check.ts'
 /** What a `.abide`'s projection is registered with the checker as, beside the `.abide`. */
-const SHADOW_SUFFIX = '.shadow.ts'
+export const SHADOW_SUFFIX = '.shadow.ts'
 
 /**
  * The two files the checker reads for one `.abide`, and how a position in either is one in it.
@@ -101,7 +101,7 @@ export class ShadowMap {
 }
 
 /** The start of the run holding `position`, plus how far in; scaffolding is the run before's end. */
-function mapBack(origins: readonly Origin[], position: number): number {
+export function mapBack(origins: readonly Origin[], position: number): number {
     let low = 0
     let high = origins.length
     while (low < high) {