docs: rework former em-dash phrasing into natural prose

Replace the mechanical em-dash-to-hyphen substitution with proper rewrites:
each former em dash becomes a colon, comma, semicolon, parentheses, a split
sentence, or a connective, chosen for natural reading. Covers docs, comments,
JSDoc, and human-facing strings across the codebase.

Created with the help of an agent.

Author: antfubot

AGENTS.md

@@ -58,7 +58,7 @@ Ahead-of-time build artifacts that live under `src/` - the shadow-root styleshee
 ## Conventions
 
 - RPC functions must use `defineRpcFunction`; always namespace IDs `devframes:plugin:<slug>:<fn-name>` for built-in devframes (the literal `plugin:` token mirrors the `@devframes/plugin-<slug>` package name on the wire - it is npm namespacing, not a concept).
-- **No magic event names - use the centralized event maps.** Every event, broadcast, shared-state key, and channel name lives in one of two source-of-truth maps: `DEVFRAME_EVENTS` (`packages/devframe/src/events.ts`, re-exported from `devframe/constants`) for the core runtime, and `HUB_EVENTS` (`packages/hub/src/events.ts`, re-exported from `@devframes/hub/constants`) for the hub. Reference `DEVFRAME_EVENTS.*` / `HUB_EVENTS.*` at call sites (`.events.emit`/`.on`, `rpc.broadcast({ method })`, `sharedState.get(key)`, `defineHubRpcFunction({ name })`, `rpc.call`) instead of re-typing a string literal. The two maps and the [`docs/content/8.references/3.events.md`](docs/content/8.references/3.events.md) Events Reference are kept in lockstep: adding, renaming, or removing a name means editing the map **and** that page in the same change - every name in the maps appears in the tables, and vice versa. The only literals left are unavoidable type-position keys (the `EventEmitter<…>` maps in `types/*` and the `DevframeRpcClientFunctions`/`DevframeRpcServerFunctions` augmentations), which mirror the maps; a package that deliberately avoids a hub dependency (e.g. `@devframes/plugin-terminals`, which models the hub bridge structurally) keeps a local literal rather than importing `HUB_EVENTS`.
+- **No magic event names: use the centralized event maps.** Every event, broadcast, shared-state key, and channel name lives in one of two source-of-truth maps: `DEVFRAME_EVENTS` (`packages/devframe/src/events.ts`, re-exported from `devframe/constants`) for the core runtime, and `HUB_EVENTS` (`packages/hub/src/events.ts`, re-exported from `@devframes/hub/constants`) for the hub. Reference `DEVFRAME_EVENTS.*` / `HUB_EVENTS.*` at call sites (`.events.emit`/`.on`, `rpc.broadcast({ method })`, `sharedState.get(key)`, `defineHubRpcFunction({ name })`, `rpc.call`) instead of re-typing a string literal. The two maps and the [`docs/content/8.references/3.events.md`](docs/content/8.references/3.events.md) Events Reference are kept in lockstep: adding, renaming, or removing a name means editing the map **and** that page in the same change; every name in the maps appears in the tables, and vice versa. The only literals left are unavoidable type-position keys (the `EventEmitter<…>` maps in `types/*` and the `DevframeRpcClientFunctions`/`DevframeRpcServerFunctions` augmentations), which mirror the maps; a package that deliberately avoids a hub dependency (e.g. `@devframes/plugin-terminals`, which models the hub bridge structurally) keeps a local literal rather than importing `HUB_EVENTS`.
 - **Stay validator-neutral.** `devframe` and every `@devframes/*` package must not introduce a preferred schema validator dependency - no `valibot`, `zod`, `arktype`, etc. in their runtime `dependencies`. `args`/`returns`/flag schemas are typed against [Standard Schema](https://standardschema.dev/) (`@standard-schema/spec`, types-only); first-party code that needs to author a schema uses the built-in zero-dep `devframe/utils/simple-schema` builder (deliberately minimal - not a general validator). JSON-schema conversion uses each schema's own Standard JSON Schema converter (`~standard.jsonSchema`, implemented by e.g. zod 4) when present and degrades to a permissive object otherwise - no converter library and no vendor dependency is required. Docs, by contrast, should point *users* at a real validator for their own integrations - recommend **valibot** (lightest) or **zod** (worth reusing if they already pull it via the JSON-render or MCP integrations).
 - Shared state via `devframe/utils/shared-state`; keep values serializable.
 - Utility imports use the package-path form `devframe/utils/*`, never relative `../utils/*`.

design/build-shadow-css.ts

@@ -38,7 +38,7 @@ export interface BuildShadowCssOptions {
   userStylePath?: string | readonly string[]
   /**
    * Prefix Wind's `--un-*` custom properties are renamed to (see
-   * `namespaceShadowCssVars`) - unique per shadow-root surface so two
+   * `namespaceShadowCssVars`), unique per shadow-root surface so two
    * shadow trees on the same host page never collide.
    */
   varPrefix: string
@@ -54,7 +54,7 @@ export interface BuildShadowCssResult {
 /**
  * Compile a shadow-root surface's UnoCSS output ahead of time into a plain
  * string module (`<srcDir>/.generated/css.ts`) that the surface adopts into
- * its shadow root - fully styled inside any host page without a global
+ * its shadow root, fully styled inside any host page without a global
  * stylesheet, and immune to the host page's own styles leaking in. Shared by
  * `@devframes/hub-ui`'s dock and `@devframes/json-render-ui`'s renderer
  * module: same pipeline, same two shadow-root gotchas (see the root
@@ -77,7 +77,7 @@ export async function buildShadowCss(options: BuildShadowCssOptions): Promise<Bu
   // Shadow-root surfaces reuse `@antfu/design`'s Vue components (buttons,
   // badges, …) directly. UnoCSS ignores `node_modules` by default, so their
   // semantic shortcut classes (`btn-primary`, `btn-action`, `badge-*`, …)
-  // would be absent from the shadow-root stylesheet - scan the design
+  // would be absent from the shadow-root stylesheet, so scan the design
   // package's component sources too so those classes ship in the injected
   // CSS.
   const designComponentsDir = join(require.resolve('@antfu/design/package.json'), '..', 'components')
@@ -111,12 +111,12 @@ export async function buildShadowCss(options: BuildShadowCssOptions): Promise<Bu
   const unoResult = await generator.generate(tokens)
   // Wind3 drops a *plain* semantic shortcut (`.bg-base` / `.color-base`) from
   // the main pass when the same shortcut also appears variant-prefixed in the
-  // sources (e.g. `@antfu/design`'s Tabs emits `data-[state=active]:bg-base`) -
+  // sources (e.g. `@antfu/design`'s Tabs emits `data-[state=active]:bg-base`),
   // a shortcut+variant interaction. Generate the shadow-surface tokens in a
   // dedicated pass so their plain (and `.dark`) rules are always present.
   const surfaces = await generator.generate(shadowSurfaceSafelist.join(' '))
   // Wind3 bakes the `primary` theme color to literal `rgb()` triplets at
-  // generate-time - rewire them to read the live `--colors-primary-*`
+  // generate-time, so rewire them to read the live `--colors-primary-*`
   // variables `primary-ramp.css` derives from `--devframe-primary`, so a
   // rebrand actually retints `text-primary`/`bg-primary`/`btn-primary`/…
   // (see `rewireBakedPrimaryColors`'s own comment).

design/dock-icon.ts

@@ -5,7 +5,7 @@
 // `ph:git-branch-duotone`) to its live, sanitized SVG markup, fetched from the
 // public `api.iconify.design` CDN. Unlike a UnoCSS `preset-icons` class, this
 // needs no `@iconify-json/*` collection installed and no hand-maintained
-// id -> class table - any Iconify id just works, at the cost of a network
+// id -> class table, since any Iconify id just works, at the cost of a network
 // round-trip on first render. We reuse @antfu/design's own fetcher, cache and
 // sanitizer (`utils/iconify.ts`) rather than reimplementing them; only the id
 // parsing and light/dark selection below are devframe-specific, mirroring the
@@ -19,7 +19,7 @@ const ICONIFY_ID = /^(?:i-)?([\w-]+):([\w-]+)$/
 
 /**
  * Resolve a dock icon (a `collection:icon` string, or a `{ light, dark }`
- * pair - the `light` variant is fetched) to its sanitized SVG markup.
+ * pair whose `light` variant is fetched) to its sanitized SVG markup.
  *
  * Returns `undefined` when the id doesn't parse or the fetch fails, so the
  * caller can fall back to a text initial.

design/uno.config.ts

@@ -17,7 +17,7 @@ export interface CreateDesignConfigOptions {
    * json-render renderer module) pass `presetWind3()` instead: Wind4 registers
    * its theme + `--un-*` custom properties via `@property { inherits: false }`
    * and keeps them in a document `:root {}` block, neither of which reaches a
-   * shadow tree - so its `color-mix(var(--colors-*))` utilities resolve to
+   * shadow tree, so its `color-mix(var(--colors-*))` utilities resolve to
    * nothing there. Wind3 bakes the same `@antfu/design` semantic utilities to
    * concrete `rgb()` + `.dark` variants, which are self-contained inside a
    * shadow root.
@@ -27,9 +27,9 @@ export interface CreateDesignConfigOptions {
 
 /**
  * Shared devframe UnoCSS base. Every plugin and example composes `@antfu/design`
- * the same way - its preset (tuned to devframe's sage green) over a Wind base,
+ * the same way: its preset (tuned to devframe's sage green) over a Wind base,
  * Phosphor icons, DM Sans/Mono web fonts, and the directive/variant-group
- * transformers - so the surfaces look and feel like one product across
+ * transformers, so the surfaces look and feel like one product across
  * frameworks. Each app extends this via `mergeConfigs([designConfig, { … }])`
  * and contributes only its own extraction globs (and any safelist).
  *
@@ -97,7 +97,7 @@ export const designConfig = createDesignConfig()
  * declared, so a host page built with Wind4 registers `--un-bg-opacity` /
  * `--un-border-opacity` / `--un-text-opacity` (et al.) as
  * `@property { syntax: '<percentage>'; inherits: false }` for the whole
- * document - including inside our shadow tree. Our shadow CSS is Wind3, which
+ * document, including inside our shadow tree. Our shadow CSS is Wind3, which
  * sets those same vars **unitless** (`--un-border-opacity: 0.13`), so the
  * global `<percentage>` registration makes every such declaration invalid and
  * the dependent `color-mix()` / `rgb(… / var(--un-*))` value collapses (a
@@ -106,9 +106,9 @@ export const designConfig = createDesignConfig()
  * The shadow stylesheet sets and reads these vars entirely within itself, so
  * renaming every `--un-` to a per-surface prefix (`--un-jr-`, `--un-hub-`)
  * keeps it self-consistent while making it immune to whatever the host page
- * registered - the renamed names are distinct properties the host's
+ * registered, since the renamed names are distinct properties the host's
  * `@property --un-*` rules never match. Apply only to shadow-injected CSS
- * (`hub-ui` dock, `json-render-ui` renderer module) - the Vite-served SPAs own
+ * (`hub-ui` dock, `json-render-ui` renderer module); the Vite-served SPAs own
  * their whole document and need no rename.
  *
  * @param css - The compiled shadow-root stylesheet.
@@ -151,15 +151,15 @@ function hexToRgbTriplet(hex: string): string | undefined {
  * variables `primary-ramp.css` derives from `--devframe-primary`.
  *
  * Wind3 (unlike Wind4) resolves each theme color to a literal `rgb(r g b /
- * <alpha>)` at compile time - the `<alpha>` slot is already dynamic (a slash
+ * <alpha>)` at compile time, and the `<alpha>` slot is already dynamic (a slash
  * literal, or the utility's own `--un-*-opacity` variable), but the base `r g
  * b` triplet is baked in, so every `primary`-based utility (`text-primary`,
  * `bg-primary`, `btn-primary`, `ring-primary-500`, …) ignores
- * `--devframe-primary` entirely - only hand-written rules that already
+ * `--devframe-primary` entirely; only hand-written rules that already
  * reference `--colors-primary-*` directly (the dock's glow gradient,
  * `primary-ramp.css` itself) retint. Swapping the baked triplet for `from
  * var(--colors-primary-<stop>, <hex>) r g b` keeps that exact alpha
- * mechanism intact while sourcing the base color from the variable - a
+ * mechanism intact while sourcing the base color from the variable, so a
  * rebrand's `--devframe-primary` now reaches every baked utility too.
  *
  * Call once per generated pass, after `generator.generate(...)`, passing the

docs/app/app.config.ts

@@ -134,11 +134,11 @@ export default defineAppConfig({
     },
     llms: {
       description:
-        'Framework-neutral foundation for building devtools - one definition becomes a Web Standard handler, a CLI, a static report, an MCP server, or a hub dock.',
+        'Framework-neutral foundation for building devtools: one definition becomes a Web Standard handler, a CLI, a static report, an MCP server, or a hub dock.',
     },
     schemaOrg: {
       description:
-        'Framework-neutral foundation for building devtools - RPC layer, hosts, and adapters.',
+        'Framework-neutral foundation for building devtools: RPC layer, hosts, and adapters.',
       applicationCategory: 'DeveloperApplication',
       operatingSystem: 'Any',
       license: 'https://github.com/devframes/devframe/blob/main/LICENSE.md',

docs/app/components/global/GettingStartedWizard.vue

@@ -3,8 +3,8 @@
  * Interactive "what should I read" wizard for the Getting Started guide.
  *
  * Every question is a grid of selectable cards (multiple answers allowed per
- * question, since a real devtool usually spans more than one answer - e.g.
- * it reads from both the node side and the user's web app). Selections
+ * question, since a real devtool usually spans more than one answer: for
+ * example, it reads from both the node side and the user's web app). Selections
  * persist to `localStorage` so a reader can leave the page and pick up where
  * they left off; the recommended reading list at the bottom recomputes from
  * whatever is currently checked.
@@ -126,22 +126,22 @@ const DOC_CATALOG: Record<string, DocEntry> = {
   '/guide/rpc': { title: 'RPC', description: 'Type-safe, bidirectional calls between the node side and the browser side.', icon: 'i-lucide-cable' },
   '/guide/shared-state': { title: 'Shared State', description: 'Observable state synced between the node side and every RPC client.', icon: 'i-lucide-refresh-cw' },
   '/guide/streaming': { title: 'Streaming', description: 'Push chunk-style data from the node side to the browser side.', icon: 'i-lucide-radio' },
-  '/guide/client-assets': { title: 'Client Assets', description: 'Where a devframe\'s built SPA lives - a local directory or an npm package.', icon: 'i-lucide-folder-tree' },
+  '/guide/client-assets': { title: 'Client Assets', description: 'Where a devframe\'s built SPA lives: a local directory or an npm package.', icon: 'i-lucide-folder-tree' },
   '/guide/client': { title: 'Client', description: 'Connects any surface to a devframe\'s node side with RPC and shared state.', icon: 'i-lucide-plug' },
   '/guide/transports': { title: 'Transports', description: 'Live RPC over WebSocket or SSE, transparent to your RPC code.', icon: 'i-lucide-waypoints' },
   '/guide/security': { title: 'Security', description: 'Localhost binding and a trust handshake before a browser can call RPC.', icon: 'i-lucide-shield-check' },
   '/guide/agent-native': { title: 'Agent-Native Devframe', description: 'Expose RPC functions, resources, and shared state to coding agents over MCP.', icon: 'i-lucide-bot' },
-  '/guide/hub': { title: 'Hub', description: 'Orchestrate many devtools sharing one UI - docks, terminals, messages, commands.', icon: 'i-lucide-layout-dashboard' },
+  '/guide/hub': { title: 'Hub', description: 'Orchestrate many devtools sharing one UI: docks, terminals, messages, commands.', icon: 'i-lucide-layout-dashboard' },
   '/guide/client-context': { title: 'Client Scripts & Client Context', description: 'How a dock client script runs a devframe\'s code inside the host page.', icon: 'i-lucide-code' },
   '/guide/hub-initiate': { title: 'Serve a Hub Anywhere', description: 'initHub() serves a whole multi-devframe install from one handler.', icon: 'i-lucide-server-cog' },
   '/guide/services': { title: 'Cross-Devframe Services', description: 'Expose a typed, namespaced capability to every devframe in a hub.', icon: 'i-lucide-share-2' },
   '/guide/deep-linking': { title: 'Deep Linking', description: 'Send a user to a specific view inside a devframe from a URL or an agent.', icon: 'i-lucide-link' },
-  '/guide/json-render': { title: 'JSON-Render', description: 'Describe a UI as data - a serializable component spec any frontend renders.', icon: 'i-lucide-braces' },
+  '/guide/json-render': { title: 'JSON-Render', description: 'Describe a UI as data: a serializable component spec any frontend renders.', icon: 'i-lucide-braces' },
   '/guide/build-your-own-json-render-frontend': { title: 'Build Your Own JSON-Render Frontend', description: 'Implement the renderer contract in your own framework instead of the reference one.', icon: 'i-lucide-component' },
-  '/guide/build-your-own-hub-ui': { title: 'Build Your Own Hub UI', description: 'The two contracts a hub UI provider implements - node side and browser side.', icon: 'i-lucide-layout-panel-left' },
+  '/guide/build-your-own-hub-ui': { title: 'Build Your Own Hub UI', description: 'The two contracts a hub UI provider implements: node side and browser side.', icon: 'i-lucide-layout-panel-left' },
   '/guide/standalone-cli': { title: 'Standalone CLI with Devframe', description: 'npx my-tool starts a dev server serving your SPA over type-safe RPC.', icon: 'i-lucide-terminal' },
   '/references/interactive-auth': { title: 'Interactive Auth', description: 'An OTP auth layer over devframe\'s node-side primitives.', icon: 'i-lucide-key-round' },
-  '/references/utilities': { title: 'Utilities', description: 'Small, stable helpers bundled into devframe - no npm install.', icon: 'i-lucide-wrench' },
+  '/references/utilities': { title: 'Utilities', description: 'Small, stable helpers bundled into devframe, no npm install.', icon: 'i-lucide-wrench' },
   '/adapters': { title: 'Adapters', description: 'Every path from a DevframeDefinition to a running devframe.', icon: 'i-lucide-shuffle' },
   '/adapters/initiate': { title: 'The Standard Handler', description: 'initDevframe() turns a definition into a Web Standard Request → Response handler.', icon: 'i-lucide-server' },
   '/adapters/cac': { title: 'CLI (cac)', description: 'A cac CLI around a DevframeDefinition with dev, build, and mcp commands.', icon: 'i-lucide-square-terminal' },