@ashley-shrok/viewmodel-shell 1.4.0 → 1.6.0

package/agent-skill.md

@@ -0,0 +1,121 @@
+# ViewModel Shell — agent operating manual
+
+This is the protocol manual for an agent driving a ViewModel Shell (VMS) app over its JSON wire. It is operational, not historical. Follow each section as a rule.
+
+## What this is
+
+VMS is a server-driven UI framework. The server is a pure function `(state, action) → (newState, view)`. Every response carries the entire UI state as an opaque blob and a fresh `vm` view tree. You do not have to render the tree to drive the API — you can read its node types and dispatch actions directly.
+
+## Endpoints
+
+Read the page's `<meta name="viewmodel-shell">` tag for the endpoint pair:
+
+```json
+{ "protocol": "viewmodel-shell/1.0", "endpoint": "/api/x", "actionEndpoint": "/api/x/action", "skill": "/.well-known/vms-skill.md" }
+```
+
+- `GET <endpoint>` → returns the initial `{ "ok": true, "vm": <ViewNode tree>, "state": <opaque state blob> }`.
+- `POST <actionEndpoint>` → dispatches an action. See the next section for the body shape.
+
+The `skill` field is optional and points at this manual (or an app-specific preamble + this manual).
+
+## Action dispatch shape
+
+Two body forms are accepted. Use JSON when you can; multipart only when uploading files.
+
+**JSON (recommended for agents).** Set `Content-Type: application/json` and POST a flat envelope:
+
+```json
+{ "name": "save-ticket-42", "state": { "...": "round-tripped state blob from the last response" } }
+```
+
+There is no `context` field — per-row / per-tab identity is encoded in the action name itself (e.g. `delete-row-42`, `filter-active`). File uploads are NOT supported in this form.
+
+**Multipart (browser-style and file-bearing).** Set `Content-Type: multipart/form-data` and post three kinds of entries:
+
+| Field | Value |
+|---|---|
+| `_action` | JSON: `{"name": "<action-name>"}` |
+| `_state` | JSON: the current state blob |
+| any file-input `name` | the binary file content (one entry per file input) |
+
+## The round-trip rule
+
+The `state` blob from the last response goes back unchanged on the next dispatch, EXCEPT for the fields the user changed. Input nodes carry a `bind` property whose value is a dotted path inside `state` where the input's value lives (e.g. `"bind": "form.title"`). Before dispatching an action that depends on user input, write your value at the bound path inside the state blob; leave every other field as you received it. The server is authoritative for everything else and may rewrite any field in the response.
+
+## Response envelope
+
+Every response carries `ok: boolean`.
+
+**Success:**
+
+```json
+{ "ok": true, "vm": { /* ViewNode tree */ }, "state": { /* opaque blob */ } }
+```
+
+Optional success-path fields, which may appear alone or alongside `vm`/`state`:
+
+| Field | Meaning |
+|---|---|
+| `redirect` | A URL string. Navigate to it (or hand control off). When `redirect` is present, `vm` and `state` may be omitted. |
+| `sideEffects` | An array of side-effect verbs (see next section). Applied in order before any redirect or re-render. |
+| `nextPollIn` | Milliseconds. Schedule a `{"name": "poll"}` dispatch after this delay. |
+| `busy` | Boolean. While `true`, drop user-initiated dispatches. Polls bypass. The next response that omits or sets `false` clears the lock. |
+| `preventUnload` | Boolean. While `true`, treat the page as having unsaved work — warn before navigating away. |
+
+**Failure:**
+
+```json
+{ "ok": false, "errors": [ { "message": "...", "code": "parse_error", "path": "form.title" } ] }
+```
+
+`errors[].path` and `errors[].code` are optional. HTTP status is 4xx or 5xx on failure. Check `ok` once at the response edge; do not branch on HTTP status.
+
+## Side-effect verbs
+
+`sideEffects[]` entries each carry a `type` discriminator. Built-in verbs as of `viewmodel-shell/1.0`:
+
+```json
+{ "sideEffects": [
+  { "type": "set-local-storage", "key": "auth_jwt", "value": "eyJ..." },
+  { "type": "set-session-storage", "key": "draft_id", "value": "42" },
+  { "type": "download", "url": "/api/invoices/42/pdf", "filename": "invoice-42.pdf" }
+] }
+```
+
+| Verb | Effect |
+|---|---|
+| `set-local-storage` | Write `key`/`value` to platform localStorage (or your agent's equivalent persistent store). |
+| `set-session-storage` | Same as above for session-scoped storage. |
+| `download` | Fetch `url` (re-presenting your auth headers — see *Auth*) and save the bytes. Filename precedence: `Content-Disposition` > side-effect `filename` > URL basename > `"download"`. |
+
+**Forward-compat rule — silently ignore unknown verbs.** A future minor release may add new verbs. If you see a `type` you do not recognize, skip it; do not error. Honor or ignore per your policy.
+
+## Errors
+
+`ok: false` responses always carry `errors[]`. The framework uses a stable code vocabulary at the protocol edge:
+
+| Code | Meaning |
+|---|---|
+| `parse_error` | The request body could not be parsed (malformed JSON, missing required field). |
+| `unknown_action` | The `name` in your action envelope does not match any handler in the current tree. |
+| `invalid_tree` | The server built a tree that violates a wire invariant (this is a server bug, not yours). |
+| `uncaught_exception` | The action handler threw. Treat as a 500-class failure. |
+
+Stop on `ok: false`. Surface the message to the user. Do not retry blindly — most of these are deterministic.
+
+## Auth
+
+The wire does not mandate an auth shape. If the app needs credentials, the app preamble above (or its own README) names them. Common patterns: a `Bearer` token in `Authorization`, a CSRF/anti-forgery token in a custom header, a session cookie. Send the same headers on every request, including polls and downloads. The `download` side-effect re-presents your auth headers when the agent fetches the file.
+
+## Polling
+
+If a response carries `nextPollIn: N`, schedule a POST `{ "name": "poll", "state": <last state> }` against the same `actionEndpoint` after `N` milliseconds. The server may continue returning `nextPollIn` until the workflow reaches a terminal state, at which point the field will be absent. Polls run silently — they are not user-initiated.
+
+## Files
+
+File uploads use the multipart form above. One form entry per file input, keyed by the input's `name` attribute (from the corresponding node's `name` field in the tree). The file's binary content is the entry's value. JSON-body dispatch cannot carry files; use multipart.
+
+## Versioning
+
+This manual applies to protocol token `viewmodel-shell/1.0` — the value of the `protocol` field on the discoverability meta tag. The protocol token tracks the wire shape, NOT the package version: a 1.5.x or 1.6.x package release may still carry protocol `viewmodel-shell/1.0` because the wire has not undergone a breaking change. A future major-version bump (`viewmodel-shell/2.0`) signals a breaking change and invalidates this manual; expect a new skill at the same `/.well-known/vms-skill.md` URL.

package/dist/browser.js

@@ -265,6 +265,58 @@ export class BrowserAdapter {
             parent.appendChild(el);
             return;
         }
+        // 1.5.0 — SectionNode.link URL-wrapper variant (issue #21). When set,
+        // emit a wrapping <a href> element instead of <section> so every native
+        // browser link affordance works for free (middle-click / Ctrl/Cmd-click
+        // new tab, right-click context menu, drag-to-bookmarks, status-bar URL).
+        // Validation guarantees link + action and link + collapsible are
+        // mutually exclusive, and link cannot be nested inside another link or
+        // action — see validateSectionAction in server.ts.
+        if (n.link) {
+            const a = document.createElement("a");
+            a.className = `vms-section vms-section--linked${n.variant === "card" ? " vms-section--card" : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}`;
+            a.href = n.link.url;
+            // Mirror LinkNode's external-attribute pattern (browser.ts ~line 666)
+            // byte-for-byte: target=_blank + rel=noopener noreferrer when external.
+            if (n.link.external) {
+                a.target = "_blank";
+                a.rel = "noopener noreferrer";
+            }
+            if (n.heading) {
+                const h = document.createElement("h2");
+                h.className = "vms-section__heading";
+                h.textContent = n.heading;
+                a.appendChild(h);
+            }
+            this.kids(n.children, a, on);
+            // Containment: clicks on nested interactive controls must NOT trigger
+            // the wrapper anchor's navigation. For non-anchor controls, stopPropagation
+            // is enough — the wrapper anchor's default navigation only fires on the
+            // anchor element itself, and stopPropagation prevents bubbled re-fires.
+            // For nested anchors (cell linkLabels), we additionally preventDefault on
+            // the click so a bubbled click cannot re-trigger the wrapper anchor's
+            // default navigation in browsers that handle nested <a> ambiguously. The
+            // catch-all `a[href]` selector includes the wrapper itself — skip it via
+            // `ctrl === a` so the wrapper's own click is NOT preventDefaulted.
+            //
+            // TODO: LinkNode-inside-section.link is left to the existing LinkNode
+            // renderer; spec-wise nested <a> is invalid HTML (issue #21 deliberately
+            // does NOT block it because the tree-validation rule only catches the
+            // sibling SectionNode-level case). A follow-up runtime warning when an
+            // inner LinkNode lives inside a section.link wrapper could surface this
+            // to consumers; until then, consumers can avoid the combo.
+            a.querySelectorAll(".vms-button, .vms-checkbox__input, .vms-checkbox, .vms-field__input, .vms-table__link, a[href]").forEach(ctrl => {
+                if (ctrl === a)
+                    return;
+                ctrl.addEventListener("click", (e) => {
+                    e.stopPropagation();
+                    if (ctrl instanceof HTMLAnchorElement)
+                        e.preventDefault();
+                });
+            });
+            parent.appendChild(a);
+            return;
+        }
         const el = document.createElement("section");
         el.className = `vms-section${n.variant === "card" ? " vms-section--card" : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}${n.action ? " vms-section--clickable" : ""}`;
         if (n.heading) {

package/dist/index.d.ts

@@ -111,6 +111,51 @@ export interface SectionNode {
      *  Omitted = today's section rendering, byte-identical (no class drift, no
      *  extra attrs, no listeners). */
     action?: ActionEvent;
+    /** URL-link navigator variant of the clickable-card primitive — the sibling
+     *  of `action` (1.4.0). Set this to make the entire section a navigational
+     *  anchor: the BrowserAdapter emits a wrapping `<a href={url}>` element so
+     *  every NATIVE browser link affordance works for free — left-click navigate,
+     *  middle-click new tab, Ctrl/Cmd-click new tab, Shift-click new window,
+     *  right-click context menu, drag-to-bookmarks, status-bar URL preview, and
+     *  accessible link semantics. No JS substitute exists for those; browsers
+     *  implement them at the anchor-element level.
+     *
+     *  Reach for `link` (this field) when the card is conceptually a
+     *  NAVIGATIONAL target (docs tile, gallery item, launcher tile). Reach for
+     *  `action` (the sibling above) when the card is a DISPATCHER that runs
+     *  server-side work. Closes [issue #21](https://github.com/ashley-shrok/ViewModelShell/issues/21).
+     *
+     *  Wire shape — INLINE object `{ url, external? }`, not flat sibling fields.
+     *  When `external: true` is set, the renderer additionally adds
+     *  `target="_blank"` and `rel="noopener noreferrer"` (mirroring LinkNode's
+     *  external attribute pattern byte-for-byte). Clicks on nested ButtonNode /
+     *  CheckboxNode / FieldNode / LinkNode / cell `linkLabel` anchors INSIDE a
+     *  linked card do NOT also fire the wrapper anchor's navigation (the
+     *  renderer stops propagation on those targets; for nested anchors it
+     *  additionally `preventDefault`s the wrapper's default so the inner anchor
+     *  wins). No `role`, no `tabindex`, no `aria-label` — the anchor element
+     *  provides every link / keyboard / focus / a11y semantic natively.
+     *
+     *  Tree validation rejects four invalid combos at the server edge with
+     *  `invalid_tree`:
+     *    (a) `link` set together with `action` on the same section — a
+     *        SectionNode is either a dispatcher (action) or a navigator (link);
+     *        they create different user expectations of what a click means.
+     *        Pick one.
+     *    (b) `link` set together with `collapsible: true` on the same section —
+     *        same rationale as action+collapsible (the summary IS the click
+     *        target; a linked card makes the whole section the click target).
+     *    (c) a SectionNode with `link` nested inside another SectionNode with
+     *        `link` — HTML5 prohibits nested `<a>` elements.
+     *    (d) a SectionNode with `link` nested inside a SectionNode with `action`
+     *        (or vice versa) — click-ownership in the overlap is ambiguous.
+     *
+     *  Omitted = today's section rendering, byte-identical (no `<a>` wrapper,
+     *  no class drift, no extra attrs). */
+    link?: {
+        url: string;
+        external?: boolean;
+    };
     children: ViewNode[];
 }
 export interface ListNode {

package/dist/server.d.ts

@@ -16,12 +16,13 @@ export * from "./index.js";
  */
 export declare function validateActionNames(vm: ViewNode): void;
 /**
- * Walk a ViewNode tree and reject two invalid SectionNode.action combos:
- * (a) action + collapsible:true on the same section, and (b) a clickable
- * section nested inside another clickable section. Pure check — does not
- * mutate the tree.
+ * Walk a ViewNode tree and reject five invalid SectionNode.action / .link
+ * combos: (a) action + collapsible:true; (b) nested action-in-action or
+ * action-in-link; (c) action + link on the same section; (d) link +
+ * collapsible:true; (e) nested link-in-link or link-in-action. Pure check —
+ * does not mutate the tree.
  *
- * @throws Error when either invalid combo is found. The message names the
+ * @throws Error when any invalid combo is found. The message names the
  *   offending section(s) by heading (or `(headingless)`).
  */
 export declare function validateSectionAction(vm: ViewNode): void;
@@ -67,6 +68,63 @@ export declare const shellSideEffect: {
      *  JSON wire, matching the .NET WhenWritingNull null-omission contract. */
     download: (url: string, filename?: string) => ShellSideEffect;
 };
+/**
+ * Mount the canonical VMS agent skill markdown as an HTTP handler.
+ *
+ * The skill is a self-contained operating manual for the VMS wire protocol
+ * (action dispatch shape, state round-trip rules, response envelope vocabulary,
+ * side-effect verbs, polling, errors, file uploads). Advertise it to agents
+ * driving your app via the `skill` field on the
+ * `<meta name="viewmodel-shell">` discoverability tag, pointing at whatever URL
+ * you mount this handler at (recommended: `/.well-known/vms-skill.md`).
+ *
+ * **Canonical source:** `viewmodel-shell/agent-skill.md` (shipped in the npm
+ * package's `files` array; the .NET package embeds a byte-identical copy at
+ * `viewmodel-shell-dotnet/AgentSkill.md` — see `parity/check-skill.ts`).
+ *
+ * **Preamble shape.** When `appPreamble` is supplied (non-empty after trim),
+ * the served body is:
+ *
+ * ```
+ * ## App-specific notes
+ *
+ * <preamble verbatim>
+ *
+ * ---
+ *
+ * <canonical-skill-body verbatim>
+ * ```
+ *
+ * When omitted (or whitespace-only), the served body is the canonical skill
+ * verbatim. The body is computed ONCE at handler-creation time; per-request
+ * cost is a single `new Response(body)`. Multiple handlers with different
+ * preambles are cheap and fully independent.
+ *
+ * **Cross-runtime.** Pure Web Fetch API — works in Bun, Deno, Hono, Cloudflare
+ * Workers, and Node 18+. The application's router owns method/path routing;
+ * the handler accepts any request and unconditionally serves the markdown body
+ * with `Content-Type: text/markdown; charset=utf-8`.
+ *
+ * @example
+ * ```ts
+ * import { createAgentSkillHandler } from "@ashley-shrok/viewmodel-shell/server";
+ * const skillHandler = createAgentSkillHandler({
+ *   appPreamble: "This is the foo app. Auth: Bearer JWT in Authorization.",
+ * });
+ * Bun.serve({
+ *   async fetch(req) {
+ *     const url = new URL(req.url);
+ *     if (url.pathname === "/.well-known/vms-skill.md" && req.method === "GET") {
+ *       return skillHandler(req);
+ *     }
+ *     // ... your other routes
+ *   },
+ * });
+ * ```
+ */
+export declare function createAgentSkillHandler(opts?: {
+    appPreamble?: string;
+}): (req: Request) => Response;
 /**
  * Thrown by an action handler to signal a malformed/invalid request. The
  * createAction wrapper catches this and returns a 400 with the error

package/dist/server.js

@@ -8,6 +8,21 @@
 // Re-export the ViewNode hierarchy and wire types so a backend can import
 // everything it needs from one place.
 export * from "./index.js";
+// ─── Canonical agent skill load (1.6.0 / 1.5.0) ──────────────────────────────
+// Loaded once at module init so createAgentSkillHandler can bake the body at
+// handler-creation time (no per-request fs work). The path resolution works for
+// BOTH layouts:
+//   - Source/dev (vitest):    src/server.ts → ../agent-skill.md
+//   - Published tarball:      dist/server.js → ../agent-skill.md (file is in
+//                             package root, listed in package.json `files`)
+// If `agent-skill.md` is missing at module init the import throws — the
+// fail-loud rule (see AGENTS.md capability-seam doc) applies: a silent 404
+// from the skill endpoint would defeat the purpose.
+import { readFileSync as __vmsReadFileSync } from "node:fs";
+import { fileURLToPath as __vmsFileURLToPath } from "node:url";
+import { dirname as __vmsDirname, join as __vmsJoin } from "node:path";
+const __vmsAgentSkillDir = __vmsDirname(__vmsFileURLToPath(import.meta.url));
+const AGENT_SKILL_MARKDOWN = __vmsReadFileSync(__vmsJoin(__vmsAgentSkillDir, "..", "agent-skill.md"), "utf8");
 /**
  * Walk a ViewNode tree and assert that every dispatch-bearing action name names
  * exactly one operation. Two occurrences are considered "the same operation"
@@ -174,68 +189,113 @@ function collectActions(node, enclosingForm, out) {
 function recordAction(action, enclosingForm, out) {
     out.push({ name: action.name, enclosingForm });
 }
-// ─── SectionNode.action shape check (1.4.0 / 260614-9hq) ─────────────────────
+// ─── SectionNode.action / .link shape checks (1.4.0 / 1.5.0) ─────────────────
 //
-// Two invalid combos a clickable-card primitive can produce at build time:
+// Five invalid combos a clickable-card or linked-card primitive can produce at
+// build time:
 //   (a) SectionNode.action set together with collapsible:true on the same
 //       section — a collapsible section's <summary> IS the click target; a
 //       clickable card makes the whole section the click target. Pick one.
 //   (b) A SectionNode with .action nested inside another SectionNode with
-//       .action — nested role="button" is an a11y violation, and
-//       click-ownership in the overlap is ambiguous.
-// A styling-only SectionNode { variant: "card" } (no .action) inside a
-// clickable card with internal buttons is VALID — only nested .action errors.
+//       .action OR .link — nested role="button"/nested-<a> is an a11y/HTML5
+//       violation, and click-ownership in the overlap is ambiguous.
+//   (c) (1.5.0) SectionNode.action set together with SectionNode.link on the
+//       same section — a section is either a dispatcher (action) or a
+//       navigator (link); they create different user expectations of a click.
+//   (d) (1.5.0) SectionNode.link set together with collapsible:true — same
+//       rationale as (a).
+//   (e) (1.5.0) A SectionNode with .link nested inside another SectionNode
+//       with .link OR .action — HTML5 prohibits nested <a> elements; the
+//       mixed case is ambiguous click-ownership.
+// A styling-only SectionNode { variant: "card" } (no .action and no .link)
+// inside a clickable or linked card with internal buttons is VALID — only
+// nested .action / .link errors.
 //
 // Mirrors viewmodel-shell-dotnet/ViewModels.cs's
 // ViewTreeValidation.ValidateSectionAction. The createAction wrapper invokes
 // this alongside validateActionNames so a server-built tree that violates
-// either rule surfaces as a 500 with code "invalid_tree" before the response
+// any rule surfaces as a 500 with code "invalid_tree" before the response
 // leaves the wire.
 /**
- * Walk a ViewNode tree and reject two invalid SectionNode.action combos:
- * (a) action + collapsible:true on the same section, and (b) a clickable
- * section nested inside another clickable section. Pure check — does not
- * mutate the tree.
+ * Walk a ViewNode tree and reject five invalid SectionNode.action / .link
+ * combos: (a) action + collapsible:true; (b) nested action-in-action or
+ * action-in-link; (c) action + link on the same section; (d) link +
+ * collapsible:true; (e) nested link-in-link or link-in-action. Pure check —
+ * does not mutate the tree.
  *
- * @throws Error when either invalid combo is found. The message names the
+ * @throws Error when any invalid combo is found. The message names the
  *   offending section(s) by heading (or `(headingless)`).
  */
 export function validateSectionAction(vm) {
     walkForSectionAction(vm, null);
 }
-function walkForSectionAction(node, outerClickable) {
+function walkForSectionAction(node, outerInteractive) {
     switch (node.type) {
         case "page": {
             const page = node;
             for (const child of page.children)
-                walkForSectionAction(child, outerClickable);
+                walkForSectionAction(child, outerInteractive);
             return;
         }
         case "section": {
             const section = node;
-            // (a) action + collapsible:true — invalid.
+            const hdr = section.heading && section.heading.length > 0
+                ? section.heading
+                : "(headingless)";
+            // (c) action + link on the same section — invalid. Checked FIRST so
+            // the most actionable message wins when the consumer accidentally sets
+            // both (they get told "pick action OR link" instead of any nested or
+            // collapsible message that follows from a still-ambiguous tree).
+            if (section.action != null && section.link != null) {
+                throw new Error(`SectionNode '${hdr}' has both Action and Link set. ` +
+                    "A SectionNode is either a dispatcher (action) or a navigator (link) — " +
+                    "they create different user expectations of what a click means. Pick one.");
+            }
+            // (d) link + collapsible:true — invalid.
+            if (section.link != null && section.collapsible === true) {
+                throw new Error(`SectionNode '${hdr}' has both Link and Collapsible: true set. ` +
+                    "A collapsible section's summary IS the click target; a linked card " +
+                    "makes the whole section the click target. Pick one.");
+            }
+            // (a) action + collapsible:true — invalid (existing, unchanged).
             if (section.action != null && section.collapsible === true) {
-                const hdr = section.heading && section.heading.length > 0
-                    ? section.heading
-                    : "(headingless)";
                 throw new Error(`SectionNode '${hdr}' has both Action and Collapsible: true set. ` +
                     "A collapsible section's summary IS the click target; a clickable card " +
                     "makes the whole section the click target. Pick one.");
             }
-            // (b) nested action-in-action — invalid.
-            if (section.action != null && outerClickable !== null) {
-                const innerHdr = section.heading && section.heading.length > 0
-                    ? section.heading
+            // (e) nested link-in-link / link-in-action — invalid.
+            if (section.link != null && outerInteractive !== null) {
+                const outerHdr = outerInteractive.heading && outerInteractive.heading.length > 0
+                    ? outerInteractive.heading
                     : "(headingless)";
-                const outerHdr = outerClickable.heading && outerClickable.heading.length > 0
-                    ? outerClickable.heading
+                if (outerInteractive.link != null) {
+                    throw new Error(`Nested SectionNode.Link: inner section '${hdr}' is inside linked outer ` +
+                        `section '${outerHdr}'. HTML5 prohibits nested <a> elements.`);
+                }
+                else {
+                    throw new Error(`SectionNode.Link inner section '${hdr}' is inside clickable outer ` +
+                        `SectionNode.Action '${outerHdr}'. Click-ownership in the overlap is ambiguous — ` +
+                        "a linked card inside a dispatcher card creates two competing primary interactions.");
+                }
+            }
+            // (b) nested action-in-action / action-in-link — invalid.
+            if (section.action != null && outerInteractive !== null) {
+                const outerHdr = outerInteractive.heading && outerInteractive.heading.length > 0
+                    ? outerInteractive.heading
                     : "(headingless)";
-                throw new Error(`Nested SectionNode.Action: inner section '${innerHdr}' is inside clickable outer ` +
-                    `section '${outerHdr}'. Nested role='button' elements are an accessibility violation, ` +
-                    "and click-ownership in the overlap is ambiguous. Use a styling-only inner section " +
-                    "(variant: 'card', no Action) with internal buttons instead.");
+                if (outerInteractive.action != null) {
+                    throw new Error(`Nested SectionNode.Action: inner section '${hdr}' is inside clickable outer ` +
+                        `section '${outerHdr}'. Nested role='button' elements are an accessibility violation, ` +
+                        "and click-ownership in the overlap is ambiguous. Use a styling-only inner section " +
+                        "(variant: 'card', no Action) with internal buttons instead.");
+                }
+                else {
+                    throw new Error(`SectionNode.Action inner section '${hdr}' is inside linked outer ` +
+                        `SectionNode.Link '${outerHdr}'. Click-ownership in the overlap is ambiguous — ` +
+                        "a dispatcher card inside a linked card creates two competing primary interactions.");
+                }
             }
-            const nextOuter = section.action != null ? section : outerClickable;
+            const nextOuter = (section.action != null || section.link != null) ? section : outerInteractive;
             for (const child of section.children)
                 walkForSectionAction(child, nextOuter);
             return;
@@ -243,28 +303,28 @@ function walkForSectionAction(node, outerClickable) {
         case "list": {
             const list = node;
             for (const child of list.children)
-                walkForSectionAction(child, outerClickable);
+                walkForSectionAction(child, outerInteractive);
             return;
         }
         case "list-item": {
             const li = node;
             for (const child of li.children)
-                walkForSectionAction(child, outerClickable);
+                walkForSectionAction(child, outerInteractive);
             return;
         }
         case "form": {
             const form = node;
             for (const child of form.children)
-                walkForSectionAction(child, outerClickable);
+                walkForSectionAction(child, outerInteractive);
             return;
         }
         case "modal": {
             const modal = node;
             for (const child of modal.children)
-                walkForSectionAction(child, outerClickable);
+                walkForSectionAction(child, outerInteractive);
             if (modal.footer) {
                 for (const child of modal.footer)
-                    walkForSectionAction(child, outerClickable);
+                    walkForSectionAction(child, outerInteractive);
             }
             return;
         }
@@ -331,6 +391,71 @@ export const shellSideEffect = {
      *  JSON wire, matching the .NET WhenWritingNull null-omission contract. */
     download: (url, filename) => ({ type: "download", url, ...(filename != null ? { filename } : {}) }),
 };
+// ─── Canonical agent skill mount helper (1.6.0 / 1.5.0) ──────────────────────
+/**
+ * Mount the canonical VMS agent skill markdown as an HTTP handler.
+ *
+ * The skill is a self-contained operating manual for the VMS wire protocol
+ * (action dispatch shape, state round-trip rules, response envelope vocabulary,
+ * side-effect verbs, polling, errors, file uploads). Advertise it to agents
+ * driving your app via the `skill` field on the
+ * `<meta name="viewmodel-shell">` discoverability tag, pointing at whatever URL
+ * you mount this handler at (recommended: `/.well-known/vms-skill.md`).
+ *
+ * **Canonical source:** `viewmodel-shell/agent-skill.md` (shipped in the npm
+ * package's `files` array; the .NET package embeds a byte-identical copy at
+ * `viewmodel-shell-dotnet/AgentSkill.md` — see `parity/check-skill.ts`).
+ *
+ * **Preamble shape.** When `appPreamble` is supplied (non-empty after trim),
+ * the served body is:
+ *
+ * ```
+ * ## App-specific notes
+ *
+ * <preamble verbatim>
+ *
+ * ---
+ *
+ * <canonical-skill-body verbatim>
+ * ```
+ *
+ * When omitted (or whitespace-only), the served body is the canonical skill
+ * verbatim. The body is computed ONCE at handler-creation time; per-request
+ * cost is a single `new Response(body)`. Multiple handlers with different
+ * preambles are cheap and fully independent.
+ *
+ * **Cross-runtime.** Pure Web Fetch API — works in Bun, Deno, Hono, Cloudflare
+ * Workers, and Node 18+. The application's router owns method/path routing;
+ * the handler accepts any request and unconditionally serves the markdown body
+ * with `Content-Type: text/markdown; charset=utf-8`.
+ *
+ * @example
+ * ```ts
+ * import { createAgentSkillHandler } from "@ashley-shrok/viewmodel-shell/server";
+ * const skillHandler = createAgentSkillHandler({
+ *   appPreamble: "This is the foo app. Auth: Bearer JWT in Authorization.",
+ * });
+ * Bun.serve({
+ *   async fetch(req) {
+ *     const url = new URL(req.url);
+ *     if (url.pathname === "/.well-known/vms-skill.md" && req.method === "GET") {
+ *       return skillHandler(req);
+ *     }
+ *     // ... your other routes
+ *   },
+ * });
+ * ```
+ */
+export function createAgentSkillHandler(opts = {}) {
+    const preamble = opts.appPreamble?.trim() ?? "";
+    const body = preamble.length === 0
+        ? AGENT_SKILL_MARKDOWN
+        : `## App-specific notes\n\n${preamble}\n\n---\n\n${AGENT_SKILL_MARKDOWN}`;
+    return (_req) => new Response(body, {
+        status: 200,
+        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+    });
+}
 // ─── Action handler factory ──────────────────────────────────────────────────
 /**
  * Thrown by an action handler to signal a malformed/invalid request. The

package/dist/tui.js

@@ -292,6 +292,12 @@ export class TuiAdapter {
             else if (a.type === "link") {
                 this.navigate(a.href);
             }
+            else if (a.type === "section-link") {
+                // 1.5.0 — SectionNode.link parity for the TUI: focused pane Enter
+                // navigates to the section's URL via the same `navigate` verb that
+                // LinkNode uses. Mirrors the BrowserAdapter's <a href> wrapper.
+                this.navigate(a.url);
+            }
             else if (a.type === "copy-button") {
                 this.copy(a.text);
             }
@@ -586,6 +592,15 @@ function focusedPaneSummary(vm, index) {
     let hasInputs = false;
     let primaryActionable = null;
     let primaryCheckbox = null;
+    // 1.5.0 — when the pane IS a section with `link.url` set, surface it as a
+    // synthetic link-actionable BEFORE scanning descendants so Enter on the
+    // focused pane navigates via the wrapper anchor's URL (mirrors how the
+    // BrowserAdapter gives a `<a href>` wrapper native link semantics for free).
+    // Descendant LinkNode/Button/etc. can still win if no section-level link
+    // is set; the section-link only seeds primaryActionable when present.
+    if (pane.type === "section" && pane.link && pane.link.url.trim().length > 0) {
+        primaryActionable = { type: "section-link", url: pane.link.url };
+    }
     const scan = (node) => {
         if (node.type === "field")
             hasInputs = true;
@@ -687,6 +702,12 @@ function paneActivationHint(summary) {
             label = a.label;
         else if (a.type === "link")
             label = a.label;
+        else if (a.type === "section-link") {
+            // 1.5.0 — synthetic actionable from SectionNode.link. No `label` field;
+            // the section's heading is shown separately by StatusBar, so use the
+            // pane's heading when available (else generic "open").
+            label = summary.heading ?? "open";
+        }
         else
             label = a.label ?? "copy"; // copy-button
         // Truncate long labels so the status bar fits a single line cleanly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "A server-driven UI framework where the wire format is structured enough that agents can build full-stack apps without ever opening a browser and all UI tests are pure unit tests with no browser runtime. Server returns a JSON tree of typed nodes; a thin TypeScript adapter renders it to DOM. Backend-agnostic — a .NET reference backend ships with the repo, but any language can produce the JSON contract.",
   "type": "module",
   "license": "MIT",
@@ -21,6 +21,7 @@
   "files": [
     "dist",
     "styles",
+    "agent-skill.md",
     "README.md",
     "LICENSE"
   ],

package/styles/default.css

@@ -234,6 +234,23 @@ body {
   outline-offset: 2px;
 }
 
+/* ── Section: linked (1.5.0 — SectionNode.link URL-wrapper variant, issue #21) ──
+   Sibling of .vms-section--clickable, applied to a wrapping <a href> instead of
+   a <section role="button">. Mirrors the clickable rules for cursor + hover +
+   :focus-visible so a linked card has the same affordance shape as a dispatcher
+   card. Additionally resets the anchor-default text styling: without these
+   `color: inherit` + `text-decoration: none` rules a linked card would render
+   with browser-default blue underlined heading text, since the wrapper element
+   is now an <a>. The `:focus-visible` outline uses the same AA-passing
+   --vms-accent token gated by the existing pair coverage, so all 12 themes
+   pass the contrast guard without additional work. */
+.vms-section--linked { cursor: pointer; color: inherit; text-decoration: none; }
+.vms-section--linked:hover { box-shadow: 0 0 0 1px var(--vms-accent-dim); }
+.vms-section--linked:focus-visible {
+  outline: 2px solid var(--vms-accent);
+  outline-offset: 2px;
+}
+
 /* ── Section: collapsible (1.2.0 — client-side disclosure via native <details>) ──
    Open/closed state is DOM-local; the BrowserAdapter snapshots and restores it
    across server-driven re-renders the same way it does for focus and scroll.