@abide/abide 0.33.1 → 0.34.0

package/src/lib/shared/health.ts

@@ -13,7 +13,7 @@ Augmented by the generated `src/.abide/health.d.ts` with
 `health()` reads type against its own hook. Unaugmented (no app.ts, or no
 hook), AppHealth resolves to no fields.
 */
-// @readme observability
+// @documentation observability
 // biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated health.d.ts
 export interface AppHealthMap {}
 export type AppHealth = AppHealthMap extends { fields: infer Fields }

package/src/lib/shared/html.ts

@@ -17,7 +17,7 @@ Calling `html` is the explicit opt-in to raw insertion; plain `{value}` always
 escapes. The tag does NOT auto-escape interpolations (it's raw by intent), so only
 build markup from values you trust, or escape them yourself.
 */
-// @readme plumbing
+// @documentation templating
 export function html(strings: TemplateStringsArray | string, ...values: unknown[]): RawHtml {
     if (typeof strings === 'string') {
         return { [RAW_HTML]: strings }

package/src/lib/shared/isSubscribable.ts

@@ -2,7 +2,7 @@ import type { Subscribable } from './types/Subscribable.ts'
 
 /*
 A Subscribable is a named AsyncIterable — distinguishes a stream argument from
-the other probe selector shapes (callables and `{ scope }` objects, neither of
+the other probe selector shapes (callables and `{ tags }` objects, neither of
 which carries Symbol.asyncIterator).
 */
 export function isSubscribable(value: unknown): value is Subscribable<unknown> {

package/src/lib/shared/log.ts

@@ -13,7 +13,7 @@ diagnostic channel (browser: the `abide-debug` localStorage key). Renders as
 the tab-separated tsv format (default) or one JSON object per line under
 ABIDE_LOG_FORMAT=json.
 */
-// @readme observability
+// @documentation observability
 export const log: Log = Object.assign(
     createChannelLog(() => appNameSlot.name ?? 'app', true),
     {

package/src/lib/shared/online.ts

@@ -40,7 +40,7 @@ const subscribeOnline =
               }
           })
 
-// @readme probes
+// @documentation probes
 export function online(): boolean {
     /* window, not navigator: Bun defines a partial navigator with no onLine. */
     if (typeof window === 'undefined') {

package/src/lib/shared/page.ts

@@ -13,7 +13,7 @@ navigation updates the snapshot (the client resolver reads a abide-ui signal).
 prefix (the server re-applies it to the proxy-stripped request URL), so compare
 active state against url() output, e.g. `page.url.pathname.startsWith(url('/x'))`.
 */
-// @readme page
+// @documentation page
 export const page: PageSnapshot = {
     get route(): string {
         return activePage().route

package/src/lib/shared/pending.ts

@@ -11,7 +11,7 @@ tail registry (streams). Pending means "no value yet":
   pending(fn)            → that function's calls (per-route spinner; remote or
                            producer, same selector grammar as cache.invalidate)
   pending(fn, args)      → exactly that call (per-row spinner)
-  pending({ scope })     → a tagged group
+  pending({ tags })      → a tagged group
   pending(subscribable)  → that stream awaiting its first frame
                            (tail.status === 'pending'; true when nothing
                            is reading yet — there is no value either way)
@@ -19,7 +19,7 @@ Probes report, never act: reading one opens no fetch and no stream. SSR
 loading state is driven by {#await}, not this. Scan semantics (tap order,
 selector grammar, registry spans) live in probeRegistries.
 */
-// @readme probes
+// @documentation probes
 export function pending<Args, Return>(
     arg?: CacheSelector<Args, Return> | Subscribable<unknown>,
     args?: Args,

package/src/lib/shared/probeRegistries.ts

@@ -16,14 +16,14 @@ re-runs whenever a matching call or stream changes state. The tap is scoped
 to the selector: a fn selector taps only its own prefix channel, so reading
 `pending(fn)` in an effect can't be re-woken by unrelated cache events (an
 effect that probes one fn and invalidates another no longer feeds itself);
-bare and scope selectors scan many entries and tap the store-wide channel. A
+bare and tag selectors scan many entries and tap the store-wide channel. A
 producer never cached resolves no prefix yet and taps store-wide — its first
 cache() marks that channel, the re-derive resolves the prefix, and the scope
 re-tracks narrowed. `matchesEntry` is the probe's cache-side question;
 `field` selects the stream-side answer; `unprobed` is the answer for a
 stream no prober can see (server, or tail never imported) — matching what
 tail() itself reports there. The bare form (no selector) spans both
-registries; fn/scope selectors are cache identities only. Outside a tracking
+registries; fn/tag selectors are cache identities only. Outside a tracking
 scope the taps are no-ops and the current value returns.
 */
 export function probeRegistries<Args, Return>(

package/src/lib/shared/refreshing.ts

@@ -9,7 +9,7 @@ value it already had while a fresher source is in flight":
   refreshing()              → anything reloading data it already had
   refreshing(fn)            → that function's calls (per-route "updating…" badge)
   refreshing(fn, args)      → exactly that call (per-row badge)
-  refreshing({ scope })     → a tagged group
+  refreshing({ tags })      → a tagged group
   refreshing(subscribable)  → that stream reconnecting with its last value
                               retained — never merely `open`; a live stream's
                               arriving frames are its normal mode, not a reload
@@ -20,7 +20,7 @@ no value yet?", refreshing answers "is a held value being superseded?".
 Probes report, never act. Scan semantics (tap order, selector grammar,
 registry spans) live in probeRegistries.
 */
-// @readme probes
+// @documentation probes
 export function refreshing<Args, Return>(
     arg?: CacheSelector<Args, Return> | Subscribable<unknown>,
     args?: Args,

package/src/lib/shared/selectorMatcher.ts

@@ -1,6 +1,6 @@
 import { keyMatchesPrefix } from './keyMatchesPrefix.ts'
 import { selectorPrefix } from './selectorPrefix.ts'
-import { toScopeSet } from './toScopeSet.ts'
+import { toTagSet } from './toTagSet.ts'
 import type { CacheEntry } from './types/CacheEntry.ts'
 import type { CacheSelector } from './types/CacheSelector.ts'
 
@@ -16,7 +16,7 @@ pending(), and refreshing() so all three interpret the call shapes identically:
   producer fn          → that producer's calls (reference id prefix). Matches
                          only if the producer was cached at least once (else it
                          has no id and nothing matches).
-  { scope }            → any entry sharing one of the requested scope tags. An
+  { tags }             → any entry sharing one of the requested tags. An
                          empty selector matches nothing.
   fn + args            → exactly that call's entry (the key derived from the
                          same encoders the read path uses); other args
@@ -46,11 +46,11 @@ export function selectorMatcher<Args, Return>(
         }
         return (entry) => keyMatchesPrefix(entry.key, prefix)
     }
-    if (arg.scope === undefined) {
+    if (arg.tags === undefined) {
         return () => false
     }
-    const requestedScopes = toScopeSet(arg.scope)
-    return (entry) => entry.scope !== undefined && intersects(entry.scope, requestedScopes)
+    const requestedTags = toTagSet(arg.tags)
+    return (entry) => entry.tags !== undefined && intersects(entry.tags, requestedTags)
 }
 
 /*
@@ -58,9 +58,9 @@ True when an entry's tags and the requested tags overlap on any tag. A plain
 for-of over the Set rather than .values().some() — Iterator Helpers are too new
 for this module's browser baseline (see producerKey).
 */
-function intersects(entryScopes: Set<string>, requestedScopes: Set<string>): boolean {
-    for (const scope of requestedScopes) {
-        if (entryScopes.has(scope)) {
+function intersects(entryTags: Set<string>, requestedTags: Set<string>): boolean {
+    for (const tag of requestedTags) {
+        if (entryTags.has(tag)) {
             return true
         }
     }

package/src/lib/shared/selectorPrefix.ts

@@ -11,7 +11,7 @@ method+url (fn and fn.raw agree — same wire identity), a producer on the
 reference id minted at first cache. With `args`, the exact entry key for that
 one call instead — derived through the same encoders the read path uses
 (keyForRemoteCall / producerKey format), so selector and entry can't
-disagree. Undefined when no prefix exists — bare and scope selectors (they
+disagree. Undefined when no prefix exists — bare and tag selectors (they
 scan, not prefix-match) and producers never cached (no id was minted;
 minting one here would leak identities for probe-only reads). The
 cache()-wrapper throw lives here so both consumers — the matcher and the

package/src/lib/shared/snippet.ts

@@ -10,7 +10,7 @@ export type Snippet<Payload> = { readonly [SNIPPET]: Payload }
    inserting escaped text. The compiler wraps a snippet's body in this — the client
    builder closes over the defining component's scope, the server string is its SSR
    render — so a snippet value passes through props like any other value. */
-// @readme plumbing
+// @documentation templating
 export function snippet<Payload>(payload: Payload): Snippet<Payload> {
     return { [SNIPPET]: payload }
 }

package/src/lib/shared/toTagSet.ts

@@ -0,0 +1,4 @@
+/* Normalizes a tags option (one tag or many) to a Set for O(1) membership. */
+export function toTagSet(tags: string | string[]): Set<string> {
+    return new Set(typeof tags === 'string' ? [tags] : tags)
+}

package/src/lib/shared/trace.ts

@@ -9,7 +9,7 @@ __SSR__ — so a client-side read returns the trace of the request that
 rendered the page. The string is propagation-ready: hand it to your own logs,
 error reports, or `propagation.extract` when attaching OpenTelemetry spans.
 */
-// @readme observability
+// @documentation observability
 export function trace(): string | undefined {
     const scope = requestScopeSlot.resolver?.()
     return scope ? formatTraceparent(scope.trace) : undefined

package/src/lib/shared/types/CacheEntry.ts

@@ -28,8 +28,8 @@ ttl = 0 = the warm value exists only to complete the hydration render and is
 evicted a macrotask later). Live entries never carry it; their ttl was fixed
 at registration.
 
-`scope` holds the cache() call's scope tags as a Set so
-`cache.invalidate({ scope })` can drop every entry sharing any tag with O(1)
+`tags` holds the cache() call's tags as a Set so
+`cache.invalidate({ tags })` can drop every entry sharing any tag with O(1)
 membership; a re-read merges new tags in rather than replacing them.
 
 `settled` flips true once the stored promise resolves. SSR snapshot
@@ -61,7 +61,7 @@ export type CacheEntry = {
     ttl: number | undefined
     expiresAt: number | undefined
     value?: unknown
-    scope?: Set<string>
+    tags?: Set<string>
     settled?: boolean
     hydrated?: boolean
     refreshing?: boolean

package/src/lib/shared/types/CacheOptions.ts

@@ -6,8 +6,8 @@ milliseconds-past-resolve that the entry stays live: omitted = forever, 0 =
 dedupe only (entry dropped once the promise settles — the mutation idiom:
 in-flight coalescing and pending() visibility, nothing retained), any other
 number = TTL.
-`scope` is one or more free-form tags grouping unrelated calls so one
-`cache.invalidate({ scope })` drops every entry sharing any of them — pass an
+`tags` is one or more free-form labels grouping unrelated calls so one
+`cache.invalidate({ tags })` drops every entry sharing any of them — pass an
 array when a call belongs to multiple invalidation groups. A unique tag (e.g. a
 uuid) shared by a set of calls gives them their own private invalidation group.
 
@@ -37,7 +37,7 @@ uncheckable — set `swr` only on a producer that is a pure read.
 */
 export type CacheOptions = {
     ttl?: number
-    scope?: string | string[]
+    tags?: string | string[]
     global?: boolean
     swr?: boolean | { throttle?: number; debounce?: number }
 }

package/src/lib/shared/types/CacheSelector.ts

@@ -8,10 +8,10 @@ Selector grammar shared by cache.invalidate(), pending(), and refreshing():
   remote fn   → that function's calls (method+url prefix); fn and fn.raw match
                 the same set since they share wire identity
   producer fn → that producer's calls (reference-id prefix)
-  { scope }   → any entry sharing one of the requested scope tags
+  { tags }    → any entry sharing one of the requested tags
 */
 export type CacheSelector<Args, Return> =
     | RemoteFunction<Args, Return>
     | RawRemoteFunction<Args>
     | ((args?: Args) => Promise<Return>)
-    | Pick<CacheOptions, 'scope'>
+    | Pick<CacheOptions, 'tags'>

package/src/lib/shared/url.ts

@@ -15,7 +15,7 @@ verb, so url('/rpc/search', { q }) types its args against the verb's own
 signature. Empty by default — an absent entry falls through to the page/asset
 branch, so the helper works before the generated d.ts lands.
 */
-// @readme url
+// @documentation url
 // biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated rpc.d.ts
 export interface RpcRoutes {}
 

package/src/lib/shared/withJsonSchema.ts

@@ -12,7 +12,7 @@ the schema is declared:
 Mutates and returns the same schema with the method attached, so the wrapped
 value stays usable everywhere the bare schema was.
 */
-// @readme rpc
+// @documentation rpc
 export function withJsonSchema<Schema extends StandardSchemaV1>(
     schema: Schema,
     toJsonSchema: (schema: Schema) => Record<string, unknown>,

package/src/lib/test/assertAgentFrameConformance.ts

@@ -15,7 +15,7 @@ Returns the collected frames plus the `done` frame so a scenario can layer
 its provider-specific assertions on top. This is the conformance seam: one
 suite of invariants, N engine adapters run against it.
 */
-// @readme plumbing
+// @documentation plumbing
 export async function assertAgentFrameConformance(
     stream: AsyncIterable<AgentFrame>,
 ): Promise<{ frames: AgentFrame[]; done: Extract<AgentFrame, { type: 'done' }> }> {

package/src/lib/test/createScriptedSurface.ts

@@ -17,7 +17,7 @@ surface out, with every `call` recorded so a test can assert exactly which
 tools an engine dispatched and with what arguments. Prompts and resources are
 empty — engines must tolerate an app exposing none.
 */
-// @readme plumbing
+// @documentation plumbing
 export function createScriptedSurface(
     tools: ScriptedTool[] = [],
 ): AgentSurface & { calls: RecordedCall[] } {

package/src/lib/test/createTestApp.ts

@@ -52,7 +52,7 @@ build's writeTestRpcDts / writeTestSocketsDts emit one entry per verb/socket
 with no imports. Empty here; types arrive once the app has been built. Mirrors
 url's RpcRoutes / health's AppHealthMap.
 */
-// @readme testing
+// @documentation testing
 // biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated testRpc.d.ts
 export interface RpcClient {}
 // biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated testSockets.d.ts

package/src/lib/ui/compile/REACTIVE_CALLEES.ts

@@ -1,7 +1,12 @@
 /* The callee names the `.abide` compiler recognises as reactive declarations
-   (`let x = state(...)`, `linked(...)`, `derived(...)`, `prop(...)`): the shared
+   (`let x = state(...)`, `linked(...)`, `computed(...)`, `prop(...)`): the shared
    "is this a reactive binding" allowlist read by the desugarer, the nested-script
    scoper, and the type-checking shadow. How each lowers — a serializable doc slot
    vs a `.value` cell — is decided per-site; this is only the membership set, so a
    new primitive is a single edit here. */
-export const REACTIVE_CALLEES: ReadonlySet<string> = new Set(['state', 'linked', 'derived', 'prop'])
+export const REACTIVE_CALLEES: ReadonlySet<string> = new Set([
+    'state',
+    'linked',
+    'computed',
+    'prop',
+])

package/src/lib/ui/compile/UI_RUNTIME_IMPORTS.ts

@@ -8,10 +8,9 @@ that populates `window.__abide`. Order is the emit order.
 export const UI_RUNTIME_IMPORTS: { name: string; specifier: string }[] = [
     { name: 'html', specifier: 'shared/html' },
     { name: 'snippet', specifier: 'shared/snippet' },
-    { name: 'doc', specifier: 'ui/doc' },
-    { name: 'state', specifier: 'ui/state' },
-    { name: 'linked', specifier: 'ui/linked' },
-    { name: 'derived', specifier: 'ui/derived' },
+    { name: 'scope', specifier: 'ui/scope' },
+    { name: 'enterScope', specifier: 'ui/enterScope' },
+    { name: 'exitScope', specifier: 'ui/exitScope' },
     { name: 'effect', specifier: 'ui/effect' },
     { name: 'mount', specifier: 'ui/dom/mount' },
     { name: 'appendText', specifier: 'ui/dom/appendText' },

package/src/lib/ui/compile/abideUiPlugin.ts

@@ -29,7 +29,7 @@ that same linked sheet, so a page renders styled before the client bundle loads,
 no inlined `<style>`. The elements still carry their `data-a-…` scope attributes
 either way (one per `<style>` covering them — see `analyzeComponent`).
 */
-// @readme plumbing
+// @documentation plumbing
 export const abideUiPlugin: BunPlugin = {
     name: 'abide-ui',
     setup(build) {

package/src/lib/ui/compile/analyzeComponent.ts

@@ -30,7 +30,7 @@ export function analyzeComponent(source: string, scopeSeed?: string): AnalyzedCo
     const scriptBody = (scriptMatch?.[1] ?? '').trim()
     const template = source.replace(/^\s*<script[^>]*>[\s\S]*?<\/script>/, '').trim()
 
-    const { code: desugared, stateNames, derivedNames } = desugarSignals(scriptBody)
+    const { code: desugared, stateNames, derivedNames, computedNames } = desugarSignals(scriptBody)
     const lowered = desugared.trim() === '' ? '' : lowerDocAccess(desugared, 'model')
     /* Hoist top-level import statements (e.g. child components) out of the script
        so the module wrapper can place them at module scope — they can't live
@@ -54,6 +54,7 @@ export function analyzeComponent(source: string, scopeSeed?: string): AnalyzedCo
         imports: imports.join('\n'),
         stateNames,
         derivedNames,
+        computedNames,
         nodes,
         styles,
         /* Hydration adopts every block in place — including `await`, which resumes

package/src/lib/ui/compile/compileComponent.ts

@@ -7,7 +7,7 @@ import type { AnalyzedComponent } from './types/AnalyzedComponent.ts'
 Compiles a single-file abide component into the body of a client build function.
 Runs the shared front-end (`analyzeComponent`), generates the DOM build from the
 template, and hoists static paths to cells. The returned body runs against a
-`host` element with `doc`/`state`/`derived`/`effect` and the dom bindings in
+`host` element with `doc`/`state`/`computed`/`effect` and the dom bindings in
 scope and defines `model` itself. `compileModule` wraps it (and the SSR body) into
 a real module; tests wrap it with `new Function`.
 
@@ -21,8 +21,8 @@ export function compileComponent(
     scopeSeed?: string,
     analyzed: AnalyzedComponent = analyzeComponent(source, scopeSeed),
 ): string {
-    const { script, stateNames, derivedNames, nodes } = analyzed
-    const build = generateBuild(nodes, 'host', stateNames, derivedNames, isLayout)
+    const { script, stateNames, derivedNames, computedNames, nodes } = analyzed
+    const build = generateBuild(nodes, 'host', stateNames, derivedNames, computedNames, isLayout)
     /* The scoped CSS is bundled into the entry stylesheet (see `abideUiPlugin`), not
        injected at runtime; the build only needs the `data-a-…` scope attributes on
        elements, which `generateBuild` reads from each node's annotated `scopes`. */

package/src/lib/ui/compile/compileModule.ts

@@ -93,6 +93,11 @@ ${options.moduleId === undefined ? '' : `component.__abideId = ${JSON.stringify(
         if (entry.name === 'mount' || entry.name === 'hydrate') {
             return true
         }
+        /* The SSR render always brackets itself with a per-render scope (compileSSR),
+           so these are referenced whenever the `render` export is — i.e. always. */
+        if (entry.name === 'enterScope' || entry.name === 'exitScope') {
+            return true
+        }
         /* Render-pass helpers are emitted by both back-ends (e.g. client and server
            await/try blocks both call nextBlockId); their names are distinctive enough
            that scanning both surfaces adds no false match. */
@@ -110,10 +115,33 @@ ${userImports}
 ${moduleBody}`
 }
 
-/* Indents a body block for embedding inside a wrapper function. */
+/* Indents a body block for embedding inside a wrapper function. Lines whose start
+   sits inside a multi-line template literal are left untouched — their leading
+   whitespace is significant string content (e.g. a CodeBlock's `code={`…`}`
+   snippet), and indenting it would corrupt the rendered sample. An odd count of
+   unescaped backticks on a line flips in/out of a literal. */
 function indent(body: string): string {
+    let insideTemplateLiteral = false
     return body
         .split('\n')
-        .map((line) => (line === '' ? line : `    ${line}`))
+        .map((line) => {
+            const indented = insideTemplateLiteral || line === '' ? line : `    ${line}`
+            if (unescapedBacktickCount(line) % 2 === 1) {
+                insideTemplateLiteral = !insideTemplateLiteral
+            }
+            return indented
+        })
         .join('\n')
 }
+
+/* Counts backticks not preceded by a backslash — the template-literal delimiters
+   on a line, ignoring escaped `\`` inside one. */
+function unescapedBacktickCount(line: string): number {
+    let count = 0
+    for (let index = 0; index < line.length; index += 1) {
+        if (line[index] === '`' && line[index - 1] !== '\\') {
+            count += 1
+        }
+    }
+    return count
+}

package/src/lib/ui/compile/compileSSR.ts

@@ -16,7 +16,7 @@ front-end, then the SSR back-end, and returns `{ html, state, awaits }`:
 Effects are stripped — they are client lifecycle and emit no HTML, so the server
 render is a snapshot of the markup before any effect runs.
 
-Runs with `doc`/`state`/`derived`/`effect`/`nextBlockId`/`enterRenderPass`/
+Runs with `doc`/`state`/`computed`/`effect`/`nextBlockId`/`enterRenderPass`/
 `exitRenderPass` in scope and defines `model`. The body is bracketed by a render
 pass so the outermost render resets the block-id counter and an inlined child
 render continues it — keeping await/try ids unique and aligned with the client.
@@ -30,16 +30,16 @@ export function compileSSR(
     scopeSeed?: string,
     analyzed: AnalyzedComponent = analyzeComponent(source, scopeSeed),
 ): string {
-    const { script, stateNames, derivedNames, nodes } = analyzed
-    const ssr = generateSSR(nodes, stateNames, derivedNames, isLayout)
+    const { script, stateNames, derivedNames, computedNames, nodes } = analyzed
+    const ssr = generateSSR(nodes, stateNames, derivedNames, computedNames, isLayout)
     /* No `<style>` in the markup — the scoped CSS is bundled into the entry stylesheet
        the shell links (see `abideUiPlugin`), so SSR output is styled by that sheet. The
        elements still carry their `data-a-…` scopes via `generateSSR`. */
     /* `typeof model` guards a component with no reactive state (a pure-async or
        static component declares no `model`); its snapshot is then empty. */
     return (
-        `enterRenderPass();\ntry {\n${stripEffects(script)}\n${SSR_ESCAPE}\nconst $out = [];\nconst $awaits = [];\n${ssr}` +
+        `enterRenderPass();\nconst $scope = enterScope();\ntry {\n${stripEffects(script)}\n${SSR_ESCAPE}\nconst $out = [];\nconst $awaits = [];\n${ssr}` +
         `return { html: $out.join(''), state: (typeof model !== 'undefined' ? model.snapshot() : {}), awaits: $awaits };\n` +
-        `} finally { exitRenderPass(); }`
+        `} finally { exitScope($scope); exitRenderPass(); }`
     )
 }