npm - @agent-native/recap-cli - Versions diffs - 0.1.0 - Mend

@agent-native/recap-cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (49) hide show

package/dist/cli.d.ts +3 -0
package/dist/cli.d.ts.map +1 -0
package/dist/cli.js +10 -0
package/dist/cli.js.map +1 -0
package/dist/index.d.ts +3 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +3 -0
package/dist/index.js.map +1 -0
package/dist/openai-compatible-endpoint.d.ts +3 -0
package/dist/openai-compatible-endpoint.d.ts.map +1 -0
package/dist/openai-compatible-endpoint.js +23 -0
package/dist/openai-compatible-endpoint.js.map +1 -0
package/dist/plan-blocks.d.ts +19 -0
package/dist/plan-blocks.d.ts.map +1 -0
package/dist/plan-blocks.js +96 -0
package/dist/plan-blocks.js.map +1 -0
package/dist/plan-publish-store.d.ts +62 -0
package/dist/plan-publish-store.d.ts.map +1 -0
package/dist/plan-publish-store.js +128 -0
package/dist/plan-publish-store.js.map +1 -0
package/dist/pr-visual-recap-workflow.d.ts +3 -0
package/dist/pr-visual-recap-workflow.d.ts.map +1 -0
package/dist/pr-visual-recap-workflow.js +3 -0
package/dist/pr-visual-recap-workflow.js.map +1 -0
package/dist/recap.d.ts +565 -0
package/dist/recap.d.ts.map +1 -0
package/dist/recap.js +3877 -0
package/dist/recap.js.map +1 -0
package/dist/skill-content/connection.d.ts +2 -0
package/dist/skill-content/connection.d.ts.map +1 -0
package/dist/skill-content/connection.js +53 -0
package/dist/skill-content/connection.js.map +1 -0
package/dist/skill-content/local-files.d.ts +2 -0
package/dist/skill-content/local-files.d.ts.map +1 -0
package/dist/skill-content/local-files.js +101 -0
package/dist/skill-content/local-files.js.map +1 -0
package/dist/skill-content/visual-recap-skill.d.ts +2 -0
package/dist/skill-content/visual-recap-skill.d.ts.map +1 -0
package/dist/skill-content/visual-recap-skill.js +548 -0
package/dist/skill-content/visual-recap-skill.js.map +1 -0
package/dist/skill-content/wireframe.d.ts +4 -0
package/dist/skill-content/wireframe.d.ts.map +1 -0
package/dist/skill-content/wireframe.js +347 -0
package/dist/skill-content/wireframe.js.map +1 -0
package/dist/skill-content.d.ts +8 -0
package/dist/skill-content.d.ts.map +1 -0
package/dist/skill-content.js +11 -0
package/dist/skill-content.js.map +1 -0
package/package.json +50 -0

package/dist/skill-content/wireframe.d.ts ADDED Viewed

@@ -0,0 +1,4 @@
+export declare const WIREFRAME_QUALITY_CORE = "<!-- SHARED-CORE:wireframe-quality START -->\n\n**A wireframe is an HTML mockup. The renderer owns the look; you write the\ncontent.** Set `data.html` to a self-contained, semantic HTML fragment of the\nscreen and set `data.surface`. The renderer owns the surface footprint/aspect,\nthe dark/light theme, the hand-drawn font, and the rough.js sketch overlay \u2014 you\nnever write `<html>`/`<body>`/`<script>`/`<style>` tags or any\nwidth/height/coordinates. You write real HTML layout and real product\ncontent; the renderer styles and roughens it.\n\n**A wireframe block's data is an HTML screen plus a surface:**\n\n```json\n{\n  \"surface\": \"browser\",\n  \"html\": \"<div style=\\\"display:flex;flex-direction:column;gap:10px;padding:16px;height:100%\\\"><h1>Sign in</h1><p class=\\\"wf-muted\\\">Use your work email to continue.</p><div class=\\\"wf-card\\\" style=\\\"display:flex;flex-direction:column;gap:10px\\\"><label>Email<input value=\\\"jane@acme.co\\\" /></label><label>Password<input value=\\\"\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\\\" /></label><label style=\\\"display:flex;align-items:center;gap:8px\\\"><input type=\\\"checkbox\\\" checked /> Remember me</label><button class=\\\"primary\\\">Sign in</button></div><a href=\\\"#\\\">Forgot password?</a></div>\"\n}\n```\n\n**Write PLAIN semantic HTML and let the renderer style it.** Bare elements\n(`h1`/`h2`/`h3`, `p`, `button`, `input`, `<input type=\"checkbox\">`, `a`, `hr`)\nare auto-themed \u2014 no classes needed. Helper classes carry the rest:\n\n- `.wf-card` / `.wf-box` \u2014 a bordered, padded container (a panel, a list item).\n- `.wf-pill` / `.wf-chip` \u2014 a rounded tag or filter; add `.accent`\n  (`<span class=\"wf-pill accent\">`) for the accent-filled variant.\n- `.wf-muted` \u2014 secondary/muted text (or use `<small>`).\n- `button.primary` or any element with `[data-primary]` \u2014 the accent-filled\n  primary button.\n\n**No decorative shadows around mockups.** Do not put `box-shadow`, `filter:\ndrop-shadow(...)`, Tailwind `shadow-*` classes, or other fake depth effects on a\nwireframe frame, root container, `.wf-card` / `.wf-box`, or canvas artboard.\nMockups should read as flat, bordered surfaces; use spacing, borders, labels,\nand annotations for separation. Only show a shadow when the real product UI\nalready has that shadow and it is essential to the change being reviewed.\n\n**Use renderer icons, not visible icon words.** For icon-only buttons or leading\nicons inside fields, chips, menu items, and toolbars, write an empty marker such\nas `<span data-icon=\"mail\" aria-label=\"Email\"></span>` or\n`<i data-icon=\"lock\"></i>`. The renderer replaces it with a Tabler-style SVG and\nthe `.wf-icon` class sizes it to the surrounding text. Supported names and\naliases: `mail`/`email`, `lock`/`password`, `search`, `plus`/`add`, `x`/`close`,\n`check`, `chevronDown`, `chevronUp`, `chevronLeft`, `chevronRight`, `dots`/`more`,\n`chevron`/`caret`/`dropdown` (down chevron), `user`, `settings`, `calendar`,\n`bell`, `send`, `edit`, `arrowLeft`, and `arrowRight`. Do not put visible words\nlike \"email\", \"lock\", \"search\", \"chevron\", or \"more\" where the product UI would\nshow an icon; use text only when it is a real label a user would read.\n\n**Use the `--wf-*` tokens for any custom color, never hex.** The renderer flips\nthese on light/dark, so reading them is what keeps a mockup correct in both\nthemes. For any inline border, background, or text color, reference a token:\n`style=\"border:1.4px solid var(--wf-line)\"`. The tokens are `--wf-ink` (text),\n`--wf-muted` (secondary text), `--wf-line` (borders/dividers), `--wf-paper`\n(page background), `--wf-card` (container surface), `--wf-accent` /\n`--wf-accent-fg` / `--wf-accent-soft` (brand action), `--wf-warn`, `--wf-ok`,\nand `--wf-radius`. Never hard-code a hex color and never set `font-family` \u2014 the\nrenderer owns the sketch/clean font.\n\n**Never use host/Tailwind theme classes in wireframe HTML.** Classes such as\n`bg-white`, `bg-zinc-50`, `bg-slate-950`, `text-zinc-950`,\n`text-slate-400`, `border-zinc-200`, `hover:bg-slate-800`, `shadow-xl`,\nor arbitrary color utilities like `bg-[#fff]` leak the host app's CSS into the\nmockup and can make dark-mode canvas frames unreadable. Use bare semantic\nelements, `.wf-*` helper classes, and `--wf-*` color tokens instead. Before\npublishing, scan every wireframe `class` and `style` attribute: if a class sets\nbackground, text, border, ring, fill, stroke, gradient, placeholder, decoration,\nor shadow color, rewrite it to renderer tokens or remove it. Layout-only classes\nare still discouraged; inline flex/grid styles are safer and easier to review.\n\n**Keep Rough.js sparse.** The renderer sketches the outer frame, standard\n`.wf-*` primitives, controls, and inline border dividers by default. Do not add\n`data-rough` to broad root wrappers, dialog shells, page panels, grid cells, or\nnested containers unless that single container is the visual point. Use\n`data-rough` only for a deliberate one-off shape. If a mockup starts looking\nlike stacked/overlapping sketch lines, remove rough targets from parent\ncontainers and let backgrounds plus spacing separate the surfaces.\n\n**Use literal CSS lengths for spacing.** The `--wf-*` tokens are for colors and\nrenderer-owned visual styling, not layout spacing. Do not use guessed spacing\ntokens such as `var(--wf-space-4)`, Tailwind spacing classes, or theme spacing\nvariables inside wireframe HTML; if a token is unavailable in the Plan renderer,\npadding collapses and content hugs the border. Use explicit CSS lengths for\nlayout: `padding:16px`, `gap:12px`, `margin-top:18px`, `minmax(0,1fr)`.\n\n**Lay out with inline `style` flex/grid.** You write the real layout \u2014\n`display:flex; flex-direction:column; gap:10px; padding:16px` and so on \u2014 and the\nrenderer never repositions anything. Compose the actual product: reproduce the\ncurrent screen, then show the modification. Real labels, real counts, real dates,\nreal button text grounded in the screen you read; not lorem or gray bars.\n\n**Surface presets \u2014 match the real footprint, never default to desktop+mobile.**\nPick the `surface` that matches what the user will actually see:\n\n- `browser`: a web page that needs a browser chrome frame around it.\n- `desktop`: a full desktop app page or app shell.\n- `mobile`: a phone screen, only when the work is genuinely mobile.\n- `popover`: a small floating menu, dropdown, or inline popover.\n- `panel`: a side panel, inspector, or sidebar widget.\n\nA sidebar popover renders as a small surface, not a desktop page and a phone\nframe. Do not emit `desktop` + `mobile` variants unless responsive behavior\nactually changes the layout. For a component or widget, show one broader\napp-context frame only when placement affects understanding, then the focused\ncomponent states.\n\n**Model the actual component shell for small surfaces.** A rendered UI change\nbelongs in a wireframe; reserve `diagram` for architecture, dependency, state,\nor data-flow relationships. Popovers, dropdown menus, command palettes, and\ncontext menus use `surface: \"popover\"` unless the surrounding page placement is\nthe point of the change. Dialogs, sheets, inspectors, sidebars, and long\nproperty panels use the matching `panel` / `desktop` surface as appropriate.\nShow the real chrome: trigger or anchor when it matters, title/header row,\ntop-right actions, separators, fields, options, selected states, body content,\nand footer actions that are visible in the workflow.\n\n**Modify, don't redesign.** When the task changes an existing screen, reproduce\nthe current screen's real layout and footprint FIRST, then change only the delta\nand call it out with a single annotation. Do not restack the page into a new\nlayout. For net-new surfaces, compose from the real app shell. Inspect the\nactual app components before drawing an existing product: sidebar density,\ntoolbar actions, overflow menus, property panels, and framework chrome should\nmatch the product unless the plan intentionally changes them.\n\n**Keep product screens pure.** A product wireframe shows the app state a user\nwould actually see. Do not embed file contracts, architecture arrows, repo pills,\nmode explanations, or implementation callouts inside the screen just to explain\nthe plan. Put those in canvas annotations, a separate diagram, or the document\nbody. Secondary UI such as properties, history, sync, export, or agent controls\nshould appear where the real product would put them: an overflow popover, sheet,\npanel, or separate framework sidebar state, not a generic permanent right\ninspector unless that inspector is the actual design.\n\n**Classify mockup scope before implementation.** Before turning a plan mockup\ninto source code, decide whether each artboard represents the whole page/app\nshell, a route body inside an existing shell, or a component/sub-surface. If an\nartboard includes navigation, sidebars, auth banners, or a signup/login form,\nmap those pieces to the real shared shell/auth components instead of nesting the\nentire mockup inside the current page. When a mockup references the product's\nstandard signup/login page, find and reuse that existing implementation; do not\napproximate it from the wireframe.\n\n**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a\npopover, menu, dialog, toast), show the full screen once, then add a small\nseparate artboard whose `html` contains ONLY that sub-surface \u2014 do not re-draw\nthe whole page around it, and do not scale a duplicate up. Pick the matching\n`surface` (e.g. `popover`) so the footprint is right; never widen a popover to\npage width.\n\n**Loading / skeleton states.** Set `data.skeleton: true` on the wireframe and\nfill the `html` with neutral, textless placeholder geometry \u2014 boxes and bars\nbuilt as `<div>`s with `background:var(--wf-line)` and explicit heights/widths,\nno labels or copy. The renderer drops borders, sketch, and color into the\nskeleton register automatically. Never escape to a `custom-html` document block\nto fake a loader.\n\n**Editing an existing mockup.** In hosted mode, to change one element, text, or\ncolor in an existing html mockup, do not regenerate the frame \u2014 call\n`update-visual-plan` with\n`contentPatches: [{ op: \"patch-wireframe-html\", blockId, edits: [{ find,\nreplace }] }]`. Each `find` is a unique snippet of the current html (read it\nfirst with `get-visual-plan`); set `all: true` on an edit to replace every\noccurrence. The result is re-sanitized. In local-files privacy mode, do not call\nhosted Plan tools; edit the local MDX source directly and rerun the local\ncheck/serve or verify command for `<plan-dir>`.\n\n**Choose the outer frame deliberately.** Wireframe and diagram data accept\n`frame: \"auto\" | \"show\" | \"hide\"` in block data (`<Screen frame=\"hide\">` in\nMDX wireframes, `<Diagram frame=\"hide\">` for MDX diagrams). Leave it unset or\n`auto` when the host context should decide: Plan and recap surfaces default to a\ndrawn outer frame; docs surfaces default to no outer frame. Use `show` for\nstandalone product screens, before/after recap comparisons, screenshot-like\nartifacts, and visuals that need containment from surrounding prose. Use `hide`\nwhen a docs page, tab, column, card, canvas artboard, or the visual's own\ninternal chrome already supplies the boundary. Do not use `hide` to compensate\nfor cramped content; fix the layout instead.\n\n**Inner padding and borders still matter.** Always wrap HTML wireframe content\nin a root container with real inner padding before drawing cards, fields, pills,\nlabels, or controls. Use at least 14-16px of padding, `box-sizing: border-box`,\n`height: 100%`, and `gap` between child rows on the root node itself so the\nfirst row never sits flush against the screen edge. Do not rely on padding on a\nnested page section as the first visible inset; the outermost element must\ncreate the breathing room. Keep text away from borders: every container, field,\nbutton, menu item, and annotation needs enough padding and line-height to read\ncleanly in the rendered Plan view.\n\n**For feature-cloud or abundance visuals, optimize the composition over line-by-line\nreading.** Some marketing/product sections need to feel like a large surface area\nof capability rather than a precise app workflow. In those cases, use one padded\nroot with a short headline and a dense, aesthetic cloud of short feature labels,\nchips, rings, or columns. Vary scale and opacity with tokens, cluster by meaning,\nand let many labels be glanceable rather than individually essential. Do not\nforce dozens of features into equal cards with long wrapped sentences; that\nusually creates a messy unreadable mockup.\n\n**Lay out children safely so they never collide.** Use HTML flex/grid with\n`gap`, `min-width: 0`, and sensible overflow. Avoid negative margins, absolute\npositioning, or fixed child widths that can collide when the renderer switches\nbetween light/dark, sketch/clean, or different zoom levels.\n\n**Do not wrap intentionally single-line labels.** For toolbars, tab rails,\nbreadcrumbs, chip/filter rows, branch and file names, file chips, and code\nfilenames \u2014 any deliberately single-line row \u2014 do not let long text wrap. Put\n`white-space: nowrap` on the row (and `overflow: hidden; text-overflow: ellipsis`\non the individual labels that can grow), so the wireframe demonstrates the actual\nlayout behavior instead of producing ugly stacked or vertical text. Use\nhorizontally scrollable or clipped rails for overflow.\n\n**Fill the frame; keep labels short.** Each artboard is a fixed-size surface \u2014 compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (`flex:1`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column \u2014 shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).\n\n**Persistent chrome bars span the full frame width.** Top bars, app headers,\ntoolbars, and bottom tab/nav bars are full-width chrome, not centered content.\nLay each one out as a single flex row that fills the frame\n(`style=\"display:flex;align-items:center;width:100%\"`) and push trailing actions\nto the right edge with a flex spacer (`<div style=\"flex:1\"></div>`) between the\nleading group and the trailing group \u2014 never center a bar inside a narrow,\ncentered block, and never let it collapse to the width of its contents. In a\nBefore/After pair the bar stays full-width in BOTH states even when one state has\nfewer controls; the spacer absorbs the difference so the remaining controls hold\ntheir edge alignment instead of sliding to the center.\n\n**Pin bottom bars to the bottom of the frame.** For mobile tab bars, footers, and\nany persistent bottom action row, make the frame itself a flex column at\n`height:100%` (`style=\"display:flex;flex-direction:column;height:100%\"`), give the\nscrolling body `flex:1` so it absorbs the slack, and place the bar as the LAST\nchild of the frame (or set `margin-top:auto` on it). The bar then sits flush at\nthe bottom of the surface instead of floating directly under the content with an\nempty band beneath it.\n\n**Before / after must be comparable.** When showing a state change, preserve the\nunchanged controls in both states so the reviewer can see exactly what moved or\nappeared; do not show an added control as a generic box floating elsewhere in\nthe surface. Place the new/changed affordance where the implementation puts it \u2014\nfor example, a new `Edit with AI` action in a popover header belongs in the\ntop-right header slot, aligned with the title, not in the body or footer. Use\nthe same frame size, scale, outer padding, border radius, and visual density on\nboth sides unless the change itself alters those properties, and let the frame\nheight fit the content rather than leaving a tall empty lower half.\n\n**Name the states with the column header, never inside the frame.** For\ndocument-body wireframes (recaps), put the two\nstates in a `columns` block and set each column's `label` to `Before` and\n`After` \u2014 the renderer draws that label as an `h4` heading above each frame. Do\nNOT bake a `Before`/`After` pill, title, or heading into the wireframe `html`: a\nlabel placed inside reads as part of the product UI, lands in a random corner,\nand clutters the comparison. The column header is the one and only place the\nstate name belongs. On a canvas, place the two state artboards as neighbors with\nframe labels \u2014 never encode Before/After inside the html.\n\n**Let the surface choose side-by-side vs. stacked.** For document-body\nwireframes (recaps), the `columns` renderer lays\nnarrow surfaces (`mobile`, `popover`, `panel`) out side by side, and\nautomatically stacks wide surfaces (`desktop`, `browser`) vertically at full\ndocument width so a large frame is never crushed into a half-width column and\ncropped. Author both wireframes with the real `surface` and the matching\n`Before`/`After` column labels; do not hand-stack the pair into separate\ntop-level wireframes or duplicate the state name as body content.\n\n**Good example \u2014 a contacts list, surface `browser`.** A small, real screen\ncomposed from the helper classes and tokens, layout in inline flex, no fonts or\nhex colors:\n\n```html\n<div\n  style=\"display:flex;flex-direction:column;gap:12px;padding:16px;height:100%\"\n>\n  <div style=\"display:flex;align-items:center;justify-content:space-between\">\n    <h1>Contacts</h1>\n    <button class=\"primary\">New contact</button>\n  </div>\n  <div style=\"display:flex;gap:6px\">\n    <span class=\"wf-pill accent\">All 128</span>\n    <span class=\"wf-pill\">Favorites</span>\n    <span class=\"wf-pill\">Archived</span>\n  </div>\n  <div\n    class=\"wf-card\"\n    style=\"display:flex;flex-direction:column;gap:0;padding:0\"\n  >\n    <div\n      style=\"display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)\"\n    >\n      <div\n        style=\"width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)\"\n      ></div>\n      <div style=\"flex:1\">\n        <strong>Jane Cooper</strong><br /><small>jane@acme.co</small>\n      </div>\n      <span class=\"wf-pill\">Lead</span>\n    </div>\n    <div style=\"display:flex;align-items:center;gap:10px;padding:10px 12px\">\n      <div\n        style=\"width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)\"\n      ></div>\n      <div style=\"flex:1\">\n        <strong>Marcus Lee</strong><br /><small>marcus@globex.io</small>\n      </div>\n      <span class=\"wf-pill\">Customer</span>\n    </div>\n  </div>\n</div>\n```\n\n<!-- SHARED-CORE:wireframe-quality END -->";
+export declare const WIREFRAME_REFERENCE_MD = "# HTML wireframe quality \u2014 single source of truth\n\nThis file is the canonical quality bar for HTML wireframes / `<Screen>` /\n`WireframeBlock` content, shared word for word by `/visual-plan` and\n`/visual-recap`. Read it in full before authoring ANY wireframe; do not\nauthor wireframes from memory or paraphrase these rules per command.\n\n<!-- SHARED-CORE:wireframe-quality START -->\n\n**A wireframe is an HTML mockup. The renderer owns the look; you write the\ncontent.** Set `data.html` to a self-contained, semantic HTML fragment of the\nscreen and set `data.surface`. The renderer owns the surface footprint/aspect,\nthe dark/light theme, the hand-drawn font, and the rough.js sketch overlay \u2014 you\nnever write `<html>`/`<body>`/`<script>`/`<style>` tags or any\nwidth/height/coordinates. You write real HTML layout and real product\ncontent; the renderer styles and roughens it.\n\n**A wireframe block's data is an HTML screen plus a surface:**\n\n```json\n{\n  \"surface\": \"browser\",\n  \"html\": \"<div style=\\\"display:flex;flex-direction:column;gap:10px;padding:16px;height:100%\\\"><h1>Sign in</h1><p class=\\\"wf-muted\\\">Use your work email to continue.</p><div class=\\\"wf-card\\\" style=\\\"display:flex;flex-direction:column;gap:10px\\\"><label>Email<input value=\\\"jane@acme.co\\\" /></label><label>Password<input value=\\\"\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022\\\" /></label><label style=\\\"display:flex;align-items:center;gap:8px\\\"><input type=\\\"checkbox\\\" checked /> Remember me</label><button class=\\\"primary\\\">Sign in</button></div><a href=\\\"#\\\">Forgot password?</a></div>\"\n}\n```\n\n**Write PLAIN semantic HTML and let the renderer style it.** Bare elements\n(`h1`/`h2`/`h3`, `p`, `button`, `input`, `<input type=\"checkbox\">`, `a`, `hr`)\nare auto-themed \u2014 no classes needed. Helper classes carry the rest:\n\n- `.wf-card` / `.wf-box` \u2014 a bordered, padded container (a panel, a list item).\n- `.wf-pill` / `.wf-chip` \u2014 a rounded tag or filter; add `.accent`\n  (`<span class=\"wf-pill accent\">`) for the accent-filled variant.\n- `.wf-muted` \u2014 secondary/muted text (or use `<small>`).\n- `button.primary` or any element with `[data-primary]` \u2014 the accent-filled\n  primary button.\n\n**No decorative shadows around mockups.** Do not put `box-shadow`, `filter:\ndrop-shadow(...)`, Tailwind `shadow-*` classes, or other fake depth effects on a\nwireframe frame, root container, `.wf-card` / `.wf-box`, or canvas artboard.\nMockups should read as flat, bordered surfaces; use spacing, borders, labels,\nand annotations for separation. Only show a shadow when the real product UI\nalready has that shadow and it is essential to the change being reviewed.\n\n**Use renderer icons, not visible icon words.** For icon-only buttons or leading\nicons inside fields, chips, menu items, and toolbars, write an empty marker such\nas `<span data-icon=\"mail\" aria-label=\"Email\"></span>` or\n`<i data-icon=\"lock\"></i>`. The renderer replaces it with a Tabler-style SVG and\nthe `.wf-icon` class sizes it to the surrounding text. Supported names and\naliases: `mail`/`email`, `lock`/`password`, `search`, `plus`/`add`, `x`/`close`,\n`check`, `chevronDown`, `chevronUp`, `chevronLeft`, `chevronRight`, `dots`/`more`,\n`chevron`/`caret`/`dropdown` (down chevron), `user`, `settings`, `calendar`,\n`bell`, `send`, `edit`, `arrowLeft`, and `arrowRight`. Do not put visible words\nlike \"email\", \"lock\", \"search\", \"chevron\", or \"more\" where the product UI would\nshow an icon; use text only when it is a real label a user would read.\n\n**Use the `--wf-*` tokens for any custom color, never hex.** The renderer flips\nthese on light/dark, so reading them is what keeps a mockup correct in both\nthemes. For any inline border, background, or text color, reference a token:\n`style=\"border:1.4px solid var(--wf-line)\"`. The tokens are `--wf-ink` (text),\n`--wf-muted` (secondary text), `--wf-line` (borders/dividers), `--wf-paper`\n(page background), `--wf-card` (container surface), `--wf-accent` /\n`--wf-accent-fg` / `--wf-accent-soft` (brand action), `--wf-warn`, `--wf-ok`,\nand `--wf-radius`. Never hard-code a hex color and never set `font-family` \u2014 the\nrenderer owns the sketch/clean font.\n\n**Never use host/Tailwind theme classes in wireframe HTML.** Classes such as\n`bg-white`, `bg-zinc-50`, `bg-slate-950`, `text-zinc-950`,\n`text-slate-400`, `border-zinc-200`, `hover:bg-slate-800`, `shadow-xl`,\nor arbitrary color utilities like `bg-[#fff]` leak the host app's CSS into the\nmockup and can make dark-mode canvas frames unreadable. Use bare semantic\nelements, `.wf-*` helper classes, and `--wf-*` color tokens instead. Before\npublishing, scan every wireframe `class` and `style` attribute: if a class sets\nbackground, text, border, ring, fill, stroke, gradient, placeholder, decoration,\nor shadow color, rewrite it to renderer tokens or remove it. Layout-only classes\nare still discouraged; inline flex/grid styles are safer and easier to review.\n\n**Keep Rough.js sparse.** The renderer sketches the outer frame, standard\n`.wf-*` primitives, controls, and inline border dividers by default. Do not add\n`data-rough` to broad root wrappers, dialog shells, page panels, grid cells, or\nnested containers unless that single container is the visual point. Use\n`data-rough` only for a deliberate one-off shape. If a mockup starts looking\nlike stacked/overlapping sketch lines, remove rough targets from parent\ncontainers and let backgrounds plus spacing separate the surfaces.\n\n**Use literal CSS lengths for spacing.** The `--wf-*` tokens are for colors and\nrenderer-owned visual styling, not layout spacing. Do not use guessed spacing\ntokens such as `var(--wf-space-4)`, Tailwind spacing classes, or theme spacing\nvariables inside wireframe HTML; if a token is unavailable in the Plan renderer,\npadding collapses and content hugs the border. Use explicit CSS lengths for\nlayout: `padding:16px`, `gap:12px`, `margin-top:18px`, `minmax(0,1fr)`.\n\n**Lay out with inline `style` flex/grid.** You write the real layout \u2014\n`display:flex; flex-direction:column; gap:10px; padding:16px` and so on \u2014 and the\nrenderer never repositions anything. Compose the actual product: reproduce the\ncurrent screen, then show the modification. Real labels, real counts, real dates,\nreal button text grounded in the screen you read; not lorem or gray bars.\n\n**Surface presets \u2014 match the real footprint, never default to desktop+mobile.**\nPick the `surface` that matches what the user will actually see:\n\n- `browser`: a web page that needs a browser chrome frame around it.\n- `desktop`: a full desktop app page or app shell.\n- `mobile`: a phone screen, only when the work is genuinely mobile.\n- `popover`: a small floating menu, dropdown, or inline popover.\n- `panel`: a side panel, inspector, or sidebar widget.\n\nA sidebar popover renders as a small surface, not a desktop page and a phone\nframe. Do not emit `desktop` + `mobile` variants unless responsive behavior\nactually changes the layout. For a component or widget, show one broader\napp-context frame only when placement affects understanding, then the focused\ncomponent states.\n\n**Model the actual component shell for small surfaces.** A rendered UI change\nbelongs in a wireframe; reserve `diagram` for architecture, dependency, state,\nor data-flow relationships. Popovers, dropdown menus, command palettes, and\ncontext menus use `surface: \"popover\"` unless the surrounding page placement is\nthe point of the change. Dialogs, sheets, inspectors, sidebars, and long\nproperty panels use the matching `panel` / `desktop` surface as appropriate.\nShow the real chrome: trigger or anchor when it matters, title/header row,\ntop-right actions, separators, fields, options, selected states, body content,\nand footer actions that are visible in the workflow.\n\n**Modify, don't redesign.** When the task changes an existing screen, reproduce\nthe current screen's real layout and footprint FIRST, then change only the delta\nand call it out with a single annotation. Do not restack the page into a new\nlayout. For net-new surfaces, compose from the real app shell. Inspect the\nactual app components before drawing an existing product: sidebar density,\ntoolbar actions, overflow menus, property panels, and framework chrome should\nmatch the product unless the plan intentionally changes them.\n\n**Keep product screens pure.** A product wireframe shows the app state a user\nwould actually see. Do not embed file contracts, architecture arrows, repo pills,\nmode explanations, or implementation callouts inside the screen just to explain\nthe plan. Put those in canvas annotations, a separate diagram, or the document\nbody. Secondary UI such as properties, history, sync, export, or agent controls\nshould appear where the real product would put them: an overflow popover, sheet,\npanel, or separate framework sidebar state, not a generic permanent right\ninspector unless that inspector is the actual design.\n\n**Classify mockup scope before implementation.** Before turning a plan mockup\ninto source code, decide whether each artboard represents the whole page/app\nshell, a route body inside an existing shell, or a component/sub-surface. If an\nartboard includes navigation, sidebars, auth banners, or a signup/login form,\nmap those pieces to the real shared shell/auth components instead of nesting the\nentire mockup inside the current page. When a mockup references the product's\nstandard signup/login page, find and reuse that existing implementation; do not\napproximate it from the wireframe.\n\n**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a\npopover, menu, dialog, toast), show the full screen once, then add a small\nseparate artboard whose `html` contains ONLY that sub-surface \u2014 do not re-draw\nthe whole page around it, and do not scale a duplicate up. Pick the matching\n`surface` (e.g. `popover`) so the footprint is right; never widen a popover to\npage width.\n\n**Loading / skeleton states.** Set `data.skeleton: true` on the wireframe and\nfill the `html` with neutral, textless placeholder geometry \u2014 boxes and bars\nbuilt as `<div>`s with `background:var(--wf-line)` and explicit heights/widths,\nno labels or copy. The renderer drops borders, sketch, and color into the\nskeleton register automatically. Never escape to a `custom-html` document block\nto fake a loader.\n\n**Editing an existing mockup.** In hosted mode, to change one element, text, or\ncolor in an existing html mockup, do not regenerate the frame \u2014 call\n`update-visual-plan` with\n`contentPatches: [{ op: \"patch-wireframe-html\", blockId, edits: [{ find,\nreplace }] }]`. Each `find` is a unique snippet of the current html (read it\nfirst with `get-visual-plan`); set `all: true` on an edit to replace every\noccurrence. The result is re-sanitized. In local-files privacy mode, do not call\nhosted Plan tools; edit the local MDX source directly and rerun the local\ncheck/serve or verify command for `<plan-dir>`.\n\n**Choose the outer frame deliberately.** Wireframe and diagram data accept\n`frame: \"auto\" | \"show\" | \"hide\"` in block data (`<Screen frame=\"hide\">` in\nMDX wireframes, `<Diagram frame=\"hide\">` for MDX diagrams). Leave it unset or\n`auto` when the host context should decide: Plan and recap surfaces default to a\ndrawn outer frame; docs surfaces default to no outer frame. Use `show` for\nstandalone product screens, before/after recap comparisons, screenshot-like\nartifacts, and visuals that need containment from surrounding prose. Use `hide`\nwhen a docs page, tab, column, card, canvas artboard, or the visual's own\ninternal chrome already supplies the boundary. Do not use `hide` to compensate\nfor cramped content; fix the layout instead.\n\n**Inner padding and borders still matter.** Always wrap HTML wireframe content\nin a root container with real inner padding before drawing cards, fields, pills,\nlabels, or controls. Use at least 14-16px of padding, `box-sizing: border-box`,\n`height: 100%`, and `gap` between child rows on the root node itself so the\nfirst row never sits flush against the screen edge. Do not rely on padding on a\nnested page section as the first visible inset; the outermost element must\ncreate the breathing room. Keep text away from borders: every container, field,\nbutton, menu item, and annotation needs enough padding and line-height to read\ncleanly in the rendered Plan view.\n\n**For feature-cloud or abundance visuals, optimize the composition over line-by-line\nreading.** Some marketing/product sections need to feel like a large surface area\nof capability rather than a precise app workflow. In those cases, use one padded\nroot with a short headline and a dense, aesthetic cloud of short feature labels,\nchips, rings, or columns. Vary scale and opacity with tokens, cluster by meaning,\nand let many labels be glanceable rather than individually essential. Do not\nforce dozens of features into equal cards with long wrapped sentences; that\nusually creates a messy unreadable mockup.\n\n**Lay out children safely so they never collide.** Use HTML flex/grid with\n`gap`, `min-width: 0`, and sensible overflow. Avoid negative margins, absolute\npositioning, or fixed child widths that can collide when the renderer switches\nbetween light/dark, sketch/clean, or different zoom levels.\n\n**Do not wrap intentionally single-line labels.** For toolbars, tab rails,\nbreadcrumbs, chip/filter rows, branch and file names, file chips, and code\nfilenames \u2014 any deliberately single-line row \u2014 do not let long text wrap. Put\n`white-space: nowrap` on the row (and `overflow: hidden; text-overflow: ellipsis`\non the individual labels that can grow), so the wireframe demonstrates the actual\nlayout behavior instead of producing ugly stacked or vertical text. Use\nhorizontally scrollable or clipped rails for overflow.\n\n**Fill the frame; keep labels short.** Each artboard is a fixed-size surface \u2014 compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (`flex:1`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column \u2014 shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).\n\n**Persistent chrome bars span the full frame width.** Top bars, app headers,\ntoolbars, and bottom tab/nav bars are full-width chrome, not centered content.\nLay each one out as a single flex row that fills the frame\n(`style=\"display:flex;align-items:center;width:100%\"`) and push trailing actions\nto the right edge with a flex spacer (`<div style=\"flex:1\"></div>`) between the\nleading group and the trailing group \u2014 never center a bar inside a narrow,\ncentered block, and never let it collapse to the width of its contents. In a\nBefore/After pair the bar stays full-width in BOTH states even when one state has\nfewer controls; the spacer absorbs the difference so the remaining controls hold\ntheir edge alignment instead of sliding to the center.\n\n**Pin bottom bars to the bottom of the frame.** For mobile tab bars, footers, and\nany persistent bottom action row, make the frame itself a flex column at\n`height:100%` (`style=\"display:flex;flex-direction:column;height:100%\"`), give the\nscrolling body `flex:1` so it absorbs the slack, and place the bar as the LAST\nchild of the frame (or set `margin-top:auto` on it). The bar then sits flush at\nthe bottom of the surface instead of floating directly under the content with an\nempty band beneath it.\n\n**Before / after must be comparable.** When showing a state change, preserve the\nunchanged controls in both states so the reviewer can see exactly what moved or\nappeared; do not show an added control as a generic box floating elsewhere in\nthe surface. Place the new/changed affordance where the implementation puts it \u2014\nfor example, a new `Edit with AI` action in a popover header belongs in the\ntop-right header slot, aligned with the title, not in the body or footer. Use\nthe same frame size, scale, outer padding, border radius, and visual density on\nboth sides unless the change itself alters those properties, and let the frame\nheight fit the content rather than leaving a tall empty lower half.\n\n**Name the states with the column header, never inside the frame.** For\ndocument-body wireframes (recaps), put the two\nstates in a `columns` block and set each column's `label` to `Before` and\n`After` \u2014 the renderer draws that label as an `h4` heading above each frame. Do\nNOT bake a `Before`/`After` pill, title, or heading into the wireframe `html`: a\nlabel placed inside reads as part of the product UI, lands in a random corner,\nand clutters the comparison. The column header is the one and only place the\nstate name belongs. On a canvas, place the two state artboards as neighbors with\nframe labels \u2014 never encode Before/After inside the html.\n\n**Let the surface choose side-by-side vs. stacked.** For document-body\nwireframes (recaps), the `columns` renderer lays\nnarrow surfaces (`mobile`, `popover`, `panel`) out side by side, and\nautomatically stacks wide surfaces (`desktop`, `browser`) vertically at full\ndocument width so a large frame is never crushed into a half-width column and\ncropped. Author both wireframes with the real `surface` and the matching\n`Before`/`After` column labels; do not hand-stack the pair into separate\ntop-level wireframes or duplicate the state name as body content.\n\n**Good example \u2014 a contacts list, surface `browser`.** A small, real screen\ncomposed from the helper classes and tokens, layout in inline flex, no fonts or\nhex colors:\n\n```html\n<div\n  style=\"display:flex;flex-direction:column;gap:12px;padding:16px;height:100%\"\n>\n  <div style=\"display:flex;align-items:center;justify-content:space-between\">\n    <h1>Contacts</h1>\n    <button class=\"primary\">New contact</button>\n  </div>\n  <div style=\"display:flex;gap:6px\">\n    <span class=\"wf-pill accent\">All 128</span>\n    <span class=\"wf-pill\">Favorites</span>\n    <span class=\"wf-pill\">Archived</span>\n  </div>\n  <div\n    class=\"wf-card\"\n    style=\"display:flex;flex-direction:column;gap:0;padding:0\"\n  >\n    <div\n      style=\"display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)\"\n    >\n      <div\n        style=\"width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)\"\n      ></div>\n      <div style=\"flex:1\">\n        <strong>Jane Cooper</strong><br /><small>jane@acme.co</small>\n      </div>\n      <span class=\"wf-pill\">Lead</span>\n    </div>\n    <div style=\"display:flex;align-items:center;gap:10px;padding:10px 12px\">\n      <div\n        style=\"width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)\"\n      ></div>\n      <div style=\"flex:1\">\n        <strong>Marcus Lee</strong><br /><small>marcus@globex.io</small>\n      </div>\n      <span class=\"wf-pill\">Customer</span>\n    </div>\n  </div>\n</div>\n```\n\n<!-- SHARED-CORE:wireframe-quality END -->\n";
+export declare const WIREFRAME_REFERENCE_POINTER = "UI recap/plan wireframes must meet a strict quality bar \u2014 full-width chrome,\npinned bottom bars, real product content, before/after comparability, the right\n`surface` preset, `--wf-*` tokens instead of hex, and no `<html>`/`<style>`/font\ntags. Before authoring ANY wireframe / `<Screen>` / `WireframeBlock`, READ\n`references/wireframe.md` in this skill directory \u2014 it is the single source of\ntruth for HTML wireframe quality, shared word for word with `/visual-plan`\nand `/visual-recap`. Do not author wireframes from memory.";
+//# sourceMappingURL=wireframe.d.ts.map

package/dist/skill-content/wireframe.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"wireframe.d.ts","sourceRoot":"","sources":["../../src/skill-content/wireframe.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,sBAAsB,8ylBAgTQ,CAAC;AAU5C,eAAO,MAAM,sBAAsB,4omBAQlC,CAAC;AAKF,eAAO,MAAM,2BAA2B,kiBAMqB,CAAC"}

package/dist/skill-content/wireframe.js ADDED Viewed

@@ -0,0 +1,347 @@
+// Single-source shared cores. Each partial is a heading-less BODY string that
+// begins and ends with its own SHARED-CORE marker comment, so the marker-region
+// sync guard can extract and compare it across the skills that consume it. The
+// skill constants below interpolate these partials at module-eval time; the
+// distributed artifact stays a flat string, so distribution is unchanged.
+//
+// Consumers:
+//   WIREFRAME_QUALITY_CORE  — visual-plan, visual-recap (surface-agnostic)
+//   CANVAS_SURFACE_CORE     — visual-plan modes (canvas/artboard mechanics)
+//   DOCUMENT_QUALITY_CORE   — visual-plan
+//   EXEMPLAR_CORE           — visual-plan
+// Surface-agnostic HTML wireframe quality rules. Applies equally to a standalone
+// WireframeBlock/<Screen> (visual-recap) and to a canvas artboard (visual-plan).
+// Do not put canvas/artboard placement mechanics here.
+export const WIREFRAME_QUALITY_CORE = `<!-- SHARED-CORE:wireframe-quality START -->
+**A wireframe is an HTML mockup. The renderer owns the look; you write the
+content.** Set \`data.html\` to a self-contained, semantic HTML fragment of the
+screen and set \`data.surface\`. The renderer owns the surface footprint/aspect,
+the dark/light theme, the hand-drawn font, and the rough.js sketch overlay — you
+never write \`<html>\`/\`<body>\`/\`<script>\`/\`<style>\` tags or any
+width/height/coordinates. You write real HTML layout and real product
+content; the renderer styles and roughens it.
+**A wireframe block's data is an HTML screen plus a surface:**
+\`\`\`json
+{
+  "surface": "browser",
+  "html": "<div style=\\"display:flex;flex-direction:column;gap:10px;padding:16px;height:100%\\"><h1>Sign in</h1><p class=\\"wf-muted\\">Use your work email to continue.</p><div class=\\"wf-card\\" style=\\"display:flex;flex-direction:column;gap:10px\\"><label>Email<input value=\\"jane@acme.co\\" /></label><label>Password<input value=\\"••••••••\\" /></label><label style=\\"display:flex;align-items:center;gap:8px\\"><input type=\\"checkbox\\" checked /> Remember me</label><button class=\\"primary\\">Sign in</button></div><a href=\\"#\\">Forgot password?</a></div>"
+}
+\`\`\`
+**Write PLAIN semantic HTML and let the renderer style it.** Bare elements
+(\`h1\`/\`h2\`/\`h3\`, \`p\`, \`button\`, \`input\`, \`<input type="checkbox">\`, \`a\`, \`hr\`)
+are auto-themed — no classes needed. Helper classes carry the rest:
+- \`.wf-card\` / \`.wf-box\` — a bordered, padded container (a panel, a list item).
+- \`.wf-pill\` / \`.wf-chip\` — a rounded tag or filter; add \`.accent\`
+  (\`<span class="wf-pill accent">\`) for the accent-filled variant.
+- \`.wf-muted\` — secondary/muted text (or use \`<small>\`).
+- \`button.primary\` or any element with \`[data-primary]\` — the accent-filled
+  primary button.
+**No decorative shadows around mockups.** Do not put \`box-shadow\`, \`filter:
+drop-shadow(...)\`, Tailwind \`shadow-*\` classes, or other fake depth effects on a
+wireframe frame, root container, \`.wf-card\` / \`.wf-box\`, or canvas artboard.
+Mockups should read as flat, bordered surfaces; use spacing, borders, labels,
+and annotations for separation. Only show a shadow when the real product UI
+already has that shadow and it is essential to the change being reviewed.
+**Use renderer icons, not visible icon words.** For icon-only buttons or leading
+icons inside fields, chips, menu items, and toolbars, write an empty marker such
+as \`<span data-icon="mail" aria-label="Email"></span>\` or
+\`<i data-icon="lock"></i>\`. The renderer replaces it with a Tabler-style SVG and
+the \`.wf-icon\` class sizes it to the surrounding text. Supported names and
+aliases: \`mail\`/\`email\`, \`lock\`/\`password\`, \`search\`, \`plus\`/\`add\`, \`x\`/\`close\`,
+\`check\`, \`chevronDown\`, \`chevronUp\`, \`chevronLeft\`, \`chevronRight\`, \`dots\`/\`more\`,
+\`chevron\`/\`caret\`/\`dropdown\` (down chevron), \`user\`, \`settings\`, \`calendar\`,
+\`bell\`, \`send\`, \`edit\`, \`arrowLeft\`, and \`arrowRight\`. Do not put visible words
+like "email", "lock", "search", "chevron", or "more" where the product UI would
+show an icon; use text only when it is a real label a user would read.
+**Use the \`--wf-*\` tokens for any custom color, never hex.** The renderer flips
+these on light/dark, so reading them is what keeps a mockup correct in both
+themes. For any inline border, background, or text color, reference a token:
+\`style="border:1.4px solid var(--wf-line)"\`. The tokens are \`--wf-ink\` (text),
+\`--wf-muted\` (secondary text), \`--wf-line\` (borders/dividers), \`--wf-paper\`
+(page background), \`--wf-card\` (container surface), \`--wf-accent\` /
+\`--wf-accent-fg\` / \`--wf-accent-soft\` (brand action), \`--wf-warn\`, \`--wf-ok\`,
+and \`--wf-radius\`. Never hard-code a hex color and never set \`font-family\` — the
+renderer owns the sketch/clean font.
+**Never use host/Tailwind theme classes in wireframe HTML.** Classes such as
+\`bg-white\`, \`bg-zinc-50\`, \`bg-slate-950\`, \`text-zinc-950\`,
+\`text-slate-400\`, \`border-zinc-200\`, \`hover:bg-slate-800\`, \`shadow-xl\`,
+or arbitrary color utilities like \`bg-[#fff]\` leak the host app's CSS into the
+mockup and can make dark-mode canvas frames unreadable. Use bare semantic
+elements, \`.wf-*\` helper classes, and \`--wf-*\` color tokens instead. Before
+publishing, scan every wireframe \`class\` and \`style\` attribute: if a class sets
+background, text, border, ring, fill, stroke, gradient, placeholder, decoration,
+or shadow color, rewrite it to renderer tokens or remove it. Layout-only classes
+are still discouraged; inline flex/grid styles are safer and easier to review.
+**Keep Rough.js sparse.** The renderer sketches the outer frame, standard
+\`.wf-*\` primitives, controls, and inline border dividers by default. Do not add
+\`data-rough\` to broad root wrappers, dialog shells, page panels, grid cells, or
+nested containers unless that single container is the visual point. Use
+\`data-rough\` only for a deliberate one-off shape. If a mockup starts looking
+like stacked/overlapping sketch lines, remove rough targets from parent
+containers and let backgrounds plus spacing separate the surfaces.
+**Use literal CSS lengths for spacing.** The \`--wf-*\` tokens are for colors and
+renderer-owned visual styling, not layout spacing. Do not use guessed spacing
+tokens such as \`var(--wf-space-4)\`, Tailwind spacing classes, or theme spacing
+variables inside wireframe HTML; if a token is unavailable in the Plan renderer,
+padding collapses and content hugs the border. Use explicit CSS lengths for
+layout: \`padding:16px\`, \`gap:12px\`, \`margin-top:18px\`, \`minmax(0,1fr)\`.
+**Lay out with inline \`style\` flex/grid.** You write the real layout —
+\`display:flex; flex-direction:column; gap:10px; padding:16px\` and so on — and the
+renderer never repositions anything. Compose the actual product: reproduce the
+current screen, then show the modification. Real labels, real counts, real dates,
+real button text grounded in the screen you read; not lorem or gray bars.
+**Surface presets — match the real footprint, never default to desktop+mobile.**
+Pick the \`surface\` that matches what the user will actually see:
+- \`browser\`: a web page that needs a browser chrome frame around it.
+- \`desktop\`: a full desktop app page or app shell.
+- \`mobile\`: a phone screen, only when the work is genuinely mobile.
+- \`popover\`: a small floating menu, dropdown, or inline popover.
+- \`panel\`: a side panel, inspector, or sidebar widget.
+A sidebar popover renders as a small surface, not a desktop page and a phone
+frame. Do not emit \`desktop\` + \`mobile\` variants unless responsive behavior
+actually changes the layout. For a component or widget, show one broader
+app-context frame only when placement affects understanding, then the focused
+component states.
+**Model the actual component shell for small surfaces.** A rendered UI change
+belongs in a wireframe; reserve \`diagram\` for architecture, dependency, state,
+or data-flow relationships. Popovers, dropdown menus, command palettes, and
+context menus use \`surface: "popover"\` unless the surrounding page placement is
+the point of the change. Dialogs, sheets, inspectors, sidebars, and long
+property panels use the matching \`panel\` / \`desktop\` surface as appropriate.
+Show the real chrome: trigger or anchor when it matters, title/header row,
+top-right actions, separators, fields, options, selected states, body content,
+and footer actions that are visible in the workflow.
+**Modify, don't redesign.** When the task changes an existing screen, reproduce
+the current screen's real layout and footprint FIRST, then change only the delta
+and call it out with a single annotation. Do not restack the page into a new
+layout. For net-new surfaces, compose from the real app shell. Inspect the
+actual app components before drawing an existing product: sidebar density,
+toolbar actions, overflow menus, property panels, and framework chrome should
+match the product unless the plan intentionally changes them.
+**Keep product screens pure.** A product wireframe shows the app state a user
+would actually see. Do not embed file contracts, architecture arrows, repo pills,
+mode explanations, or implementation callouts inside the screen just to explain
+the plan. Put those in canvas annotations, a separate diagram, or the document
+body. Secondary UI such as properties, history, sync, export, or agent controls
+should appear where the real product would put them: an overflow popover, sheet,
+panel, or separate framework sidebar state, not a generic permanent right
+inspector unless that inspector is the actual design.
+**Classify mockup scope before implementation.** Before turning a plan mockup
+into source code, decide whether each artboard represents the whole page/app
+shell, a route body inside an existing shell, or a component/sub-surface. If an
+artboard includes navigation, sidebars, auth banners, or a signup/login form,
+map those pieces to the real shared shell/auth components instead of nesting the
+entire mockup inside the current page. When a mockup references the product's
+standard signup/login page, find and reuse that existing implementation; do not
+approximate it from the wireframe.
+**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a
+popover, menu, dialog, toast), show the full screen once, then add a small
+separate artboard whose \`html\` contains ONLY that sub-surface — do not re-draw
+the whole page around it, and do not scale a duplicate up. Pick the matching
+\`surface\` (e.g. \`popover\`) so the footprint is right; never widen a popover to
+page width.
+**Loading / skeleton states.** Set \`data.skeleton: true\` on the wireframe and
+fill the \`html\` with neutral, textless placeholder geometry — boxes and bars
+built as \`<div>\`s with \`background:var(--wf-line)\` and explicit heights/widths,
+no labels or copy. The renderer drops borders, sketch, and color into the
+skeleton register automatically. Never escape to a \`custom-html\` document block
+to fake a loader.
+**Editing an existing mockup.** In hosted mode, to change one element, text, or
+color in an existing html mockup, do not regenerate the frame — call
+\`update-visual-plan\` with
+\`contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
+replace }] }]\`. Each \`find\` is a unique snippet of the current html (read it
+first with \`get-visual-plan\`); set \`all: true\` on an edit to replace every
+occurrence. The result is re-sanitized. In local-files privacy mode, do not call
+hosted Plan tools; edit the local MDX source directly and rerun the local
+check/serve or verify command for \`<plan-dir>\`.
+**Choose the outer frame deliberately.** Wireframe and diagram data accept
+\`frame: "auto" | "show" | "hide"\` in block data (\`<Screen frame="hide">\` in
+MDX wireframes, \`<Diagram frame="hide">\` for MDX diagrams). Leave it unset or
+\`auto\` when the host context should decide: Plan and recap surfaces default to a
+drawn outer frame; docs surfaces default to no outer frame. Use \`show\` for
+standalone product screens, before/after recap comparisons, screenshot-like
+artifacts, and visuals that need containment from surrounding prose. Use \`hide\`
+when a docs page, tab, column, card, canvas artboard, or the visual's own
+internal chrome already supplies the boundary. Do not use \`hide\` to compensate
+for cramped content; fix the layout instead.
+**Inner padding and borders still matter.** Always wrap HTML wireframe content
+in a root container with real inner padding before drawing cards, fields, pills,
+labels, or controls. Use at least 14-16px of padding, \`box-sizing: border-box\`,
+\`height: 100%\`, and \`gap\` between child rows on the root node itself so the
+first row never sits flush against the screen edge. Do not rely on padding on a
+nested page section as the first visible inset; the outermost element must
+create the breathing room. Keep text away from borders: every container, field,
+button, menu item, and annotation needs enough padding and line-height to read
+cleanly in the rendered Plan view.
+**For feature-cloud or abundance visuals, optimize the composition over line-by-line
+reading.** Some marketing/product sections need to feel like a large surface area
+of capability rather than a precise app workflow. In those cases, use one padded
+root with a short headline and a dense, aesthetic cloud of short feature labels,
+chips, rings, or columns. Vary scale and opacity with tokens, cluster by meaning,
+and let many labels be glanceable rather than individually essential. Do not
+force dozens of features into equal cards with long wrapped sentences; that
+usually creates a messy unreadable mockup.
+**Lay out children safely so they never collide.** Use HTML flex/grid with
+\`gap\`, \`min-width: 0\`, and sensible overflow. Avoid negative margins, absolute
+positioning, or fixed child widths that can collide when the renderer switches
+between light/dark, sketch/clean, or different zoom levels.
+**Do not wrap intentionally single-line labels.** For toolbars, tab rails,
+breadcrumbs, chip/filter rows, branch and file names, file chips, and code
+filenames — any deliberately single-line row — do not let long text wrap. Put
+\`white-space: nowrap\` on the row (and \`overflow: hidden; text-overflow: ellipsis\`
+on the individual labels that can grow), so the wireframe demonstrates the actual
+layout behavior instead of producing ugly stacked or vertical text. Use
+horizontally scrollable or clipped rails for overflow.
+**Fill the frame; keep labels short.** Each artboard is a fixed-size surface — compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (\`flex:1\`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column — shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).
+**Persistent chrome bars span the full frame width.** Top bars, app headers,
+toolbars, and bottom tab/nav bars are full-width chrome, not centered content.
+Lay each one out as a single flex row that fills the frame
+(\`style="display:flex;align-items:center;width:100%"\`) and push trailing actions
+to the right edge with a flex spacer (\`<div style="flex:1"></div>\`) between the
+leading group and the trailing group — never center a bar inside a narrow,
+centered block, and never let it collapse to the width of its contents. In a
+Before/After pair the bar stays full-width in BOTH states even when one state has
+fewer controls; the spacer absorbs the difference so the remaining controls hold
+their edge alignment instead of sliding to the center.
+**Pin bottom bars to the bottom of the frame.** For mobile tab bars, footers, and
+any persistent bottom action row, make the frame itself a flex column at
+\`height:100%\` (\`style="display:flex;flex-direction:column;height:100%"\`), give the
+scrolling body \`flex:1\` so it absorbs the slack, and place the bar as the LAST
+child of the frame (or set \`margin-top:auto\` on it). The bar then sits flush at
+the bottom of the surface instead of floating directly under the content with an
+empty band beneath it.
+**Before / after must be comparable.** When showing a state change, preserve the
+unchanged controls in both states so the reviewer can see exactly what moved or
+appeared; do not show an added control as a generic box floating elsewhere in
+the surface. Place the new/changed affordance where the implementation puts it —
+for example, a new \`Edit with AI\` action in a popover header belongs in the
+top-right header slot, aligned with the title, not in the body or footer. Use
+the same frame size, scale, outer padding, border radius, and visual density on
+both sides unless the change itself alters those properties, and let the frame
+height fit the content rather than leaving a tall empty lower half.
+**Name the states with the column header, never inside the frame.** For
+document-body wireframes (recaps), put the two
+states in a \`columns\` block and set each column's \`label\` to \`Before\` and
+\`After\` — the renderer draws that label as an \`h4\` heading above each frame. Do
+NOT bake a \`Before\`/\`After\` pill, title, or heading into the wireframe \`html\`: a
+label placed inside reads as part of the product UI, lands in a random corner,
+and clutters the comparison. The column header is the one and only place the
+state name belongs. On a canvas, place the two state artboards as neighbors with
+frame labels — never encode Before/After inside the html.
+**Let the surface choose side-by-side vs. stacked.** For document-body
+wireframes (recaps), the \`columns\` renderer lays
+narrow surfaces (\`mobile\`, \`popover\`, \`panel\`) out side by side, and
+automatically stacks wide surfaces (\`desktop\`, \`browser\`) vertically at full
+document width so a large frame is never crushed into a half-width column and
+cropped. Author both wireframes with the real \`surface\` and the matching
+\`Before\`/\`After\` column labels; do not hand-stack the pair into separate
+top-level wireframes or duplicate the state name as body content.
+**Good example — a contacts list, surface \`browser\`.** A small, real screen
+composed from the helper classes and tokens, layout in inline flex, no fonts or
+hex colors:
+\`\`\`html
+<div
+  style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%"
+>
+  <div style="display:flex;align-items:center;justify-content:space-between">
+    <h1>Contacts</h1>
+    <button class="primary">New contact</button>
+  </div>
+  <div style="display:flex;gap:6px">
+    <span class="wf-pill accent">All 128</span>
+    <span class="wf-pill">Favorites</span>
+    <span class="wf-pill">Archived</span>
+  </div>
+  <div
+    class="wf-card"
+    style="display:flex;flex-direction:column;gap:0;padding:0"
+  >
+    <div
+      style="display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)"
+    >
+      <div
+        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
+      ></div>
+      <div style="flex:1">
+        <strong>Jane Cooper</strong><br /><small>jane@acme.co</small>
+      </div>
+      <span class="wf-pill">Lead</span>
+    </div>
+    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px">
+      <div
+        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
+      ></div>
+      <div style="flex:1">
+        <strong>Marcus Lee</strong><br /><small>marcus@globex.io</small>
+      </div>
+      <span class="wf-pill">Customer</span>
+    </div>
+  </div>
+</div>
+\`\`\`
+<!-- SHARED-CORE:wireframe-quality END -->`;
+// Progressive-disclosure reference file. `WIREFRAME_QUALITY_CORE` is the single
+// source of truth for HTML wireframe quality; it is materialized verbatim into a
+// sibling `references/wireframe.md` in EVERY plan skill dir (visual-plan and
+// visual-recap), instead of being interpolated inline into each SKILL.md body.
+// The SKILL.md bodies carry only `WIREFRAME_REFERENCE_POINTER`, which tells the
+// agent to read this file before authoring any wireframe. Keeping the reference
+// body byte-identical to the core (markers included) lets the sync guard assert
+// the on-disk copies never drift from the canonical constant.
+export const WIREFRAME_REFERENCE_MD = `# HTML wireframe quality — single source of truth
+This file is the canonical quality bar for HTML wireframes / \`<Screen>\` /
+\`WireframeBlock\` content, shared word for word by \`/visual-plan\` and
+\`/visual-recap\`. Read it in full before authoring ANY wireframe; do not
+author wireframes from memory or paraphrase these rules per command.
+${WIREFRAME_QUALITY_CORE}
+`;
+// Short pointer that replaces the inline wireframe-quality core in each SKILL.md
+// body. Authoring quality lives in the sibling reference file so the SKILL.md
+// stays lean (progressive disclosure); the agent loads the detail on demand.
+export const WIREFRAME_REFERENCE_POINTER = `UI recap/plan wireframes must meet a strict quality bar — full-width chrome,
+pinned bottom bars, real product content, before/after comparability, the right
+\`surface\` preset, \`--wf-*\` tokens instead of hex, and no \`<html>\`/\`<style>\`/font
+tags. Before authoring ANY wireframe / \`<Screen>\` / \`WireframeBlock\`, READ
+\`references/wireframe.md\` in this skill directory — it is the single source of
+truth for HTML wireframe quality, shared word for word with \`/visual-plan\`
+and \`/visual-recap\`. Do not author wireframes from memory.`;
+//# sourceMappingURL=wireframe.js.map

package/dist/skill-content/wireframe.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"wireframe.js","sourceRoot":"","sources":["../../src/skill-content/wireframe.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,0EAA0E;AAC1E,EAAE;AACF,aAAa;AACb,2EAA2E;AAC3E,4EAA4E;AAC5E,0CAA0C;AAC1C,0CAA0C;AAE1C,iFAAiF;AACjF,iFAAiF;AACjF,uDAAuD;AACvD,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2CAgTK,CAAC;AAE5C,gFAAgF;AAChF,iFAAiF;AACjF,6EAA6E;AAC7E,+EAA+E;AAC/E,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAChF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;EAOpC,sBAAsB;CACvB,CAAC;AAEF,iFAAiF;AACjF,8EAA8E;AAC9E,6EAA6E;AAC7E,MAAM,CAAC,MAAM,2BAA2B,GAAG;;;;;;6DAMkB,CAAC","sourcesContent":["// Single-source shared cores. Each partial is a heading-less BODY string that\n// begins and ends with its own SHARED-CORE marker comment, so the marker-region\n// sync guard can extract and compare it across the skills that consume it. The\n// skill constants below interpolate these partials at module-eval time; the\n// distributed artifact stays a flat string, so distribution is unchanged.\n//\n// Consumers:\n// WIREFRAME_QUALITY_CORE — visual-plan, visual-recap (surface-agnostic)\n// CANVAS_SURFACE_CORE — visual-plan modes (canvas/artboard mechanics)\n// DOCUMENT_QUALITY_CORE — visual-plan\n// EXEMPLAR_CORE — visual-plan\n\n// Surface-agnostic HTML wireframe quality rules. Applies equally to a standalone\n// WireframeBlock/<Screen> (visual-recap) and to a canvas artboard (visual-plan).\n// Do not put canvas/artboard placement mechanics here.\nexport const WIREFRAME_QUALITY_CORE = `\n\n**A wireframe is an HTML mockup. The renderer owns the look; you write the\ncontent.** Set \\`data.html\\` to a self-contained, semantic HTML fragment of the\nscreen and set \\`data.surface\\`. The renderer owns the surface footprint/aspect,\nthe dark/light theme, the hand-drawn font, and the rough.js sketch overlay — you\nnever write \\`<html>\\`/\\`<body>\\`/\\`<script>\\`/\\`<style>\\` tags or any\nwidth/height/coordinates. You write real HTML layout and real product\ncontent; the renderer styles and roughens it.\n\n**A wireframe block's data is an HTML screen plus a surface:**\n\n\\`\\`\\`json\n{\n \"surface\": \"browser\",\n \"html\": \"<div style=\\\\\"display:flex;flex-direction:column;gap:10px;padding:16px;height:100%\\\\\"><h1>Sign in</h1><p class=\\\\\"wf-muted\\\\\">Use your work email to continue.</p><div class=\\\\\"wf-card\\\\\" style=\\\\\"display:flex;flex-direction:column;gap:10px\\\\\"><label>Email<input value=\\\\\"jane@acme.co\\\\\" /></label><label>Password<input value=\\\\\"••••••••\\\\\" /></label><label style=\\\\\"display:flex;align-items:center;gap:8px\\\\\"><input type=\\\\\"checkbox\\\\\" checked /> Remember me</label><button class=\\\\\"primary\\\\\">Sign in</button></div><a href=\\\\\"#\\\\\">Forgot password?</a></div>\"\n}\n\\`\\`\\`\n\n**Write PLAIN semantic HTML and let the renderer style it.** Bare elements\n(\\`h1\\`/\\`h2\\`/\\`h3\\`, \\`p\\`, \\`button\\`, \\`input\\`, \\`<input type=\"checkbox\">\\`, \\`a\\`, \\`hr\\`)\nare auto-themed — no classes needed. Helper classes carry the rest:\n\n- \\`.wf-card\\` / \\`.wf-box\\` — a bordered, padded container (a panel, a list item).\n- \\`.wf-pill\\` / \\`.wf-chip\\` — a rounded tag or filter; add \\`.accent\\`\n (\\`<span class=\"wf-pill accent\">\\`) for the accent-filled variant.\n- \\`.wf-muted\\` — secondary/muted text (or use \\`<small>\\`).\n- \\`button.primary\\` or any element with \\`[data-primary]\\` — the accent-filled\n primary button.\n\n**No decorative shadows around mockups.** Do not put \\`box-shadow\\`, \\`filter:\ndrop-shadow(...)\\`, Tailwind \\`shadow-*\\` classes, or other fake depth effects on a\nwireframe frame, root container, \\`.wf-card\\` / \\`.wf-box\\`, or canvas artboard.\nMockups should read as flat, bordered surfaces; use spacing, borders, labels,\nand annotations for separation. Only show a shadow when the real product UI\nalready has that shadow and it is essential to the change being reviewed.\n\n**Use renderer icons, not visible icon words.** For icon-only buttons or leading\nicons inside fields, chips, menu items, and toolbars, write an empty marker such\nas \\`<span data-icon=\"mail\" aria-label=\"Email\"></span>\\` or\n\\`<i data-icon=\"lock\"></i>\\`. The renderer replaces it with a Tabler-style SVG and\nthe \\`.wf-icon\\` class sizes it to the surrounding text. Supported names and\naliases: \\`mail\\`/\\`email\\`, \\`lock\\`/\\`password\\`, \\`search\\`, \\`plus\\`/\\`add\\`, \\`x\\`/\\`close\\`,\n\\`check\\`, \\`chevronDown\\`, \\`chevronUp\\`, \\`chevronLeft\\`, \\`chevronRight\\`, \\`dots\\`/\\`more\\`,\n\\`chevron\\`/\\`caret\\`/\\`dropdown\\` (down chevron), \\`user\\`, \\`settings\\`, \\`calendar\\`,\n\\`bell\\`, \\`send\\`, \\`edit\\`, \\`arrowLeft\\`, and \\`arrowRight\\`. Do not put visible words\nlike \"email\", \"lock\", \"search\", \"chevron\", or \"more\" where the product UI would\nshow an icon; use text only when it is a real label a user would read.\n\n**Use the \\`--wf-*\\` tokens for any custom color, never hex.** The renderer flips\nthese on light/dark, so reading them is what keeps a mockup correct in both\nthemes. For any inline border, background, or text color, reference a token:\n\\`style=\"border:1.4px solid var(--wf-line)\"\\`. The tokens are \\`--wf-ink\\` (text),\n\\`--wf-muted\\` (secondary text), \\`--wf-line\\` (borders/dividers), \\`--wf-paper\\`\n(page background), \\`--wf-card\\` (container surface), \\`--wf-accent\\` /\n\\`--wf-accent-fg\\` / \\`--wf-accent-soft\\` (brand action), \\`--wf-warn\\`, \\`--wf-ok\\`,\nand \\`--wf-radius\\`. Never hard-code a hex color and never set \\`font-family\\` — the\nrenderer owns the sketch/clean font.\n\n**Never use host/Tailwind theme classes in wireframe HTML.** Classes such as\n\\`bg-white\\`, \\`bg-zinc-50\\`, \\`bg-slate-950\\`, \\`text-zinc-950\\`,\n\\`text-slate-400\\`, \\`border-zinc-200\\`, \\`hover:bg-slate-800\\`, \\`shadow-xl\\`,\nor arbitrary color utilities like \\`bg-[#fff]\\` leak the host app's CSS into the\nmockup and can make dark-mode canvas frames unreadable. Use bare semantic\nelements, \\`.wf-*\\` helper classes, and \\`--wf-*\\` color tokens instead. Before\npublishing, scan every wireframe \\`class\\` and \\`style\\` attribute: if a class sets\nbackground, text, border, ring, fill, stroke, gradient, placeholder, decoration,\nor shadow color, rewrite it to renderer tokens or remove it. Layout-only classes\nare still discouraged; inline flex/grid styles are safer and easier to review.\n\n**Keep Rough.js sparse.** The renderer sketches the outer frame, standard\n\\`.wf-*\\` primitives, controls, and inline border dividers by default. Do not add\n\\`data-rough\\` to broad root wrappers, dialog shells, page panels, grid cells, or\nnested containers unless that single container is the visual point. Use\n\\`data-rough\\` only for a deliberate one-off shape. If a mockup starts looking\nlike stacked/overlapping sketch lines, remove rough targets from parent\ncontainers and let backgrounds plus spacing separate the surfaces.\n\n**Use literal CSS lengths for spacing.** The \\`--wf-*\\` tokens are for colors and\nrenderer-owned visual styling, not layout spacing. Do not use guessed spacing\ntokens such as \\`var(--wf-space-4)\\`, Tailwind spacing classes, or theme spacing\nvariables inside wireframe HTML; if a token is unavailable in the Plan renderer,\npadding collapses and content hugs the border. Use explicit CSS lengths for\nlayout: \\`padding:16px\\`, \\`gap:12px\\`, \\`margin-top:18px\\`, \\`minmax(0,1fr)\\`.\n\n**Lay out with inline \\`style\\` flex/grid.** You write the real layout —\n\\`display:flex; flex-direction:column; gap:10px; padding:16px\\` and so on — and the\nrenderer never repositions anything. Compose the actual product: reproduce the\ncurrent screen, then show the modification. Real labels, real counts, real dates,\nreal button text grounded in the screen you read; not lorem or gray bars.\n\n**Surface presets — match the real footprint, never default to desktop+mobile.**\nPick the \\`surface\\` that matches what the user will actually see:\n\n- \\`browser\\`: a web page that needs a browser chrome frame around it.\n- \\`desktop\\`: a full desktop app page or app shell.\n- \\`mobile\\`: a phone screen, only when the work is genuinely mobile.\n- \\`popover\\`: a small floating menu, dropdown, or inline popover.\n- \\`panel\\`: a side panel, inspector, or sidebar widget.\n\nA sidebar popover renders as a small surface, not a desktop page and a phone\nframe. Do not emit \\`desktop\\` + \\`mobile\\` variants unless responsive behavior\nactually changes the layout. For a component or widget, show one broader\napp-context frame only when placement affects understanding, then the focused\ncomponent states.\n\n**Model the actual component shell for small surfaces.** A rendered UI change\nbelongs in a wireframe; reserve \\`diagram\\` for architecture, dependency, state,\nor data-flow relationships. Popovers, dropdown menus, command palettes, and\ncontext menus use \\`surface: \"popover\"\\` unless the surrounding page placement is\nthe point of the change. Dialogs, sheets, inspectors, sidebars, and long\nproperty panels use the matching \\`panel\\` / \\`desktop\\` surface as appropriate.\nShow the real chrome: trigger or anchor when it matters, title/header row,\ntop-right actions, separators, fields, options, selected states, body content,\nand footer actions that are visible in the workflow.\n\n**Modify, don't redesign.** When the task changes an existing screen, reproduce\nthe current screen's real layout and footprint FIRST, then change only the delta\nand call it out with a single annotation. Do not restack the page into a new\nlayout. For net-new surfaces, compose from the real app shell. Inspect the\nactual app components before drawing an existing product: sidebar density,\ntoolbar actions, overflow menus, property panels, and framework chrome should\nmatch the product unless the plan intentionally changes them.\n\n**Keep product screens pure.** A product wireframe shows the app state a user\nwould actually see. Do not embed file contracts, architecture arrows, repo pills,\nmode explanations, or implementation callouts inside the screen just to explain\nthe plan. Put those in canvas annotations, a separate diagram, or the document\nbody. Secondary UI such as properties, history, sync, export, or agent controls\nshould appear where the real product would put them: an overflow popover, sheet,\npanel, or separate framework sidebar state, not a generic permanent right\ninspector unless that inspector is the actual design.\n\n**Classify mockup scope before implementation.** Before turning a plan mockup\ninto source code, decide whether each artboard represents the whole page/app\nshell, a route body inside an existing shell, or a component/sub-surface. If an\nartboard includes navigation, sidebars, auth banners, or a signup/login form,\nmap those pieces to the real shared shell/auth components instead of nesting the\nentire mockup inside the current page. When a mockup references the product's\nstandard signup/login page, find and reuse that existing implementation; do not\napproximate it from the wireframe.\n\n**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a\npopover, menu, dialog, toast), show the full screen once, then add a small\nseparate artboard whose \\`html\\` contains ONLY that sub-surface — do not re-draw\nthe whole page around it, and do not scale a duplicate up. Pick the matching\n\\`surface\\` (e.g. \\`popover\\`) so the footprint is right; never widen a popover to\npage width.\n\n**Loading / skeleton states.** Set \\`data.skeleton: true\\` on the wireframe and\nfill the \\`html\\` with neutral, textless placeholder geometry — boxes and bars\nbuilt as \\`<div>\\`s with \\`background:var(--wf-line)\\` and explicit heights/widths,\nno labels or copy. The renderer drops borders, sketch, and color into the\nskeleton register automatically. Never escape to a \\`custom-html\\` document block\nto fake a loader.\n\n**Editing an existing mockup.** In hosted mode, to change one element, text, or\ncolor in an existing html mockup, do not regenerate the frame — call\n\\`update-visual-plan\\` with\n\\`contentPatches: [{ op: \"patch-wireframe-html\", blockId, edits: [{ find,\nreplace }] }]\\`. Each \\`find\\` is a unique snippet of the current html (read it\nfirst with \\`get-visual-plan\\`); set \\`all: true\\` on an edit to replace every\noccurrence. The result is re-sanitized. In local-files privacy mode, do not call\nhosted Plan tools; edit the local MDX source directly and rerun the local\ncheck/serve or verify command for \\`<plan-dir>\\`.\n\n**Choose the outer frame deliberately.** Wireframe and diagram data accept\n\\`frame: \"auto\" | \"show\" | \"hide\"\\` in block data (\\`<Screen frame=\"hide\">\\` in\nMDX wireframes, \\`<Diagram frame=\"hide\">\\` for MDX diagrams). Leave it unset or\n\\`auto\\` when the host context should decide: Plan and recap surfaces default to a\ndrawn outer frame; docs surfaces default to no outer frame. Use \\`show\\` for\nstandalone product screens, before/after recap comparisons, screenshot-like\nartifacts, and visuals that need containment from surrounding prose. Use \\`hide\\`\nwhen a docs page, tab, column, card, canvas artboard, or the visual's own\ninternal chrome already supplies the boundary. Do not use \\`hide\\` to compensate\nfor cramped content; fix the layout instead.\n\n**Inner padding and borders still matter.** Always wrap HTML wireframe content\nin a root container with real inner padding before drawing cards, fields, pills,\nlabels, or controls. Use at least 14-16px of padding, \\`box-sizing: border-box\\`,\n\\`height: 100%\\`, and \\`gap\\` between child rows on the root node itself so the\nfirst row never sits flush against the screen edge. Do not rely on padding on a\nnested page section as the first visible inset; the outermost element must\ncreate the breathing room. Keep text away from borders: every container, field,\nbutton, menu item, and annotation needs enough padding and line-height to read\ncleanly in the rendered Plan view.\n\n**For feature-cloud or abundance visuals, optimize the composition over line-by-line\nreading.** Some marketing/product sections need to feel like a large surface area\nof capability rather than a precise app workflow. In those cases, use one padded\nroot with a short headline and a dense, aesthetic cloud of short feature labels,\nchips, rings, or columns. Vary scale and opacity with tokens, cluster by meaning,\nand let many labels be glanceable rather than individually essential. Do not\nforce dozens of features into equal cards with long wrapped sentences; that\nusually creates a messy unreadable mockup.\n\n**Lay out children safely so they never collide.** Use HTML flex/grid with\n\\`gap\\`, \\`min-width: 0\\`, and sensible overflow. Avoid negative margins, absolute\npositioning, or fixed child widths that can collide when the renderer switches\nbetween light/dark, sketch/clean, or different zoom levels.\n\n**Do not wrap intentionally single-line labels.** For toolbars, tab rails,\nbreadcrumbs, chip/filter rows, branch and file names, file chips, and code\nfilenames — any deliberately single-line row — do not let long text wrap. Put\n\\`white-space: nowrap\\` on the row (and \\`overflow: hidden; text-overflow: ellipsis\\`\non the individual labels that can grow), so the wireframe demonstrates the actual\nlayout behavior instead of producing ugly stacked or vertical text. Use\nhorizontally scrollable or clipped rails for overflow.\n\n**Fill the frame; keep labels short.** Each artboard is a fixed-size surface — compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (\\`flex:1\\`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column — shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).\n\n**Persistent chrome bars span the full frame width.** Top bars, app headers,\ntoolbars, and bottom tab/nav bars are full-width chrome, not centered content.\nLay each one out as a single flex row that fills the frame\n(\\`style=\"display:flex;align-items:center;width:100%\"\\`) and push trailing actions\nto the right edge with a flex spacer (\\`<div style=\"flex:1\"></div>\\`) between the\nleading group and the trailing group — never center a bar inside a narrow,\ncentered block, and never let it collapse to the width of its contents. In a\nBefore/After pair the bar stays full-width in BOTH states even when one state has\nfewer controls; the spacer absorbs the difference so the remaining controls hold\ntheir edge alignment instead of sliding to the center.\n\n**Pin bottom bars to the bottom of the frame.** For mobile tab bars, footers, and\nany persistent bottom action row, make the frame itself a flex column at\n\\`height:100%\\` (\\`style=\"display:flex;flex-direction:column;height:100%\"\\`), give the\nscrolling body \\`flex:1\\` so it absorbs the slack, and place the bar as the LAST\nchild of the frame (or set \\`margin-top:auto\\` on it). The bar then sits flush at\nthe bottom of the surface instead of floating directly under the content with an\nempty band beneath it.\n\n**Before / after must be comparable.** When showing a state change, preserve the\nunchanged controls in both states so the reviewer can see exactly what moved or\nappeared; do not show an added control as a generic box floating elsewhere in\nthe surface. Place the new/changed affordance where the implementation puts it —\nfor example, a new \\`Edit with AI\\` action in a popover header belongs in the\ntop-right header slot, aligned with the title, not in the body or footer. Use\nthe same frame size, scale, outer padding, border radius, and visual density on\nboth sides unless the change itself alters those properties, and let the frame\nheight fit the content rather than leaving a tall empty lower half.\n\n**Name the states with the column header, never inside the frame.** For\ndocument-body wireframes (recaps), put the two\nstates in a \\`columns\\` block and set each column's \\`label\\` to \\`Before\\` and\n\\`After\\` — the renderer draws that label as an \\`h4\\` heading above each frame. Do\nNOT bake a \\`Before\\`/\\`After\\` pill, title, or heading into the wireframe \\`html\\`: a\nlabel placed inside reads as part of the product UI, lands in a random corner,\nand clutters the comparison. The column header is the one and only place the\nstate name belongs. On a canvas, place the two state artboards as neighbors with\nframe labels — never encode Before/After inside the html.\n\n**Let the surface choose side-by-side vs. stacked.** For document-body\nwireframes (recaps), the \\`columns\\` renderer lays\nnarrow surfaces (\\`mobile\\`, \\`popover\\`, \\`panel\\`) out side by side, and\nautomatically stacks wide surfaces (\\`desktop\\`, \\`browser\\`) vertically at full\ndocument width so a large frame is never crushed into a half-width column and\ncropped. Author both wireframes with the real \\`surface\\` and the matching\n\\`Before\\`/\\`After\\` column labels; do not hand-stack the pair into separate\ntop-level wireframes or duplicate the state name as body content.\n\n**Good example — a contacts list, surface \\`browser\\`.** A small, real screen\ncomposed from the helper classes and tokens, layout in inline flex, no fonts or\nhex colors:\n\n\\`\\`\\`html\n<div\n style=\"display:flex;flex-direction:column;gap:12px;padding:16px;height:100%\"\n>\n <div style=\"display:flex;align-items:center;justify-content:space-between\">\n <h1>Contacts</h1>\n <button class=\"primary\">New contact</button>\n </div>\n <div style=\"display:flex;gap:6px\">\n <span class=\"wf-pill accent\">All 128</span>\n <span class=\"wf-pill\">Favorites</span>\n <span class=\"wf-pill\">Archived</span>\n </div>\n <div\n class=\"wf-card\"\n style=\"display:flex;flex-direction:column;gap:0;padding:0\"\n >\n <div\n style=\"display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)\"\n >\n <div\n style=\"width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)\"\n ></div>\n <div style=\"flex:1\">\n <strong>Jane Cooper</strong><br /><small>jane@acme.co</small>\n </div>\n <span class=\"wf-pill\">Lead</span>\n </div>\n <div style=\"display:flex;align-items:center;gap:10px;padding:10px 12px\">\n <div\n style=\"width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)\"\n ></div>\n <div style=\"flex:1\">\n <strong>Marcus Lee</strong><br /><small>marcus@globex.io</small>\n </div>\n <span class=\"wf-pill\">Customer</span>\n </div>\n </div>\n</div>\n\\`\\`\\`\n\n`;\n\n// Progressive-disclosure reference file. `WIREFRAME_QUALITY_CORE` is the single\n// source of truth for HTML wireframe quality; it is materialized verbatim into a\n// sibling `references/wireframe.md` in EVERY plan skill dir (visual-plan and\n// visual-recap), instead of being interpolated inline into each SKILL.md body.\n// The SKILL.md bodies carry only `WIREFRAME_REFERENCE_POINTER`, which tells the\n// agent to read this file before authoring any wireframe. Keeping the reference\n// body byte-identical to the core (markers included) lets the sync guard assert\n// the on-disk copies never drift from the canonical constant.\nexport const WIREFRAME_REFERENCE_MD = `# HTML wireframe quality — single source of truth\n\nThis file is the canonical quality bar for HTML wireframes / \\`<Screen>\\` /\n\\`WireframeBlock\\` content, shared word for word by \\`/visual-plan\\` and\n\\`/visual-recap\\`. Read it in full before authoring ANY wireframe; do not\nauthor wireframes from memory or paraphrase these rules per command.\n\n${WIREFRAME_QUALITY_CORE}\n`;\n\n// Short pointer that replaces the inline wireframe-quality core in each SKILL.md\n// body. Authoring quality lives in the sibling reference file so the SKILL.md\n// stays lean (progressive disclosure); the agent loads the detail on demand.\nexport const WIREFRAME_REFERENCE_POINTER = `UI recap/plan wireframes must meet a strict quality bar — full-width chrome,\npinned bottom bars, real product content, before/after comparability, the right\n\\`surface\\` preset, \\`--wf-*\\` tokens instead of hex, and no \\`<html>\\`/\\`<style>\\`/font\ntags. Before authoring ANY wireframe / \\`<Screen>\\` / \\`WireframeBlock\\`, READ\n\\`references/wireframe.md\\` in this skill directory — it is the single source of\ntruth for HTML wireframe quality, shared word for word with \\`/visual-plan\\`\nand \\`/visual-recap\\`. Do not author wireframes from memory.`;\n"]}

package/dist/skill-content.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+import { VISUAL_RECAP_SKILL_MD } from "./skill-content/visual-recap-skill.js";
+export { VISUAL_RECAP_SKILL_MD };
+export declare const RECAP_REFERENCE_FILES: {
+    "references/wireframe.md": string;
+    "references/connection.md": string;
+    "references/local-files.md": string;
+};
+//# sourceMappingURL=skill-content.d.ts.map

package/dist/skill-content.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"skill-content.d.ts","sourceRoot":"","sources":["../src/skill-content.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAG9E,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAEjC,eAAO,MAAM,qBAAqB;;;;CAIjC,CAAC"}

package/dist/skill-content.js ADDED Viewed

@@ -0,0 +1,11 @@
+import { CONNECTION_REFERENCE_MD } from "./skill-content/connection.js";
+import { LOCAL_FILES_REFERENCE_MD } from "./skill-content/local-files.js";
+import { VISUAL_RECAP_SKILL_MD } from "./skill-content/visual-recap-skill.js";
+import { WIREFRAME_REFERENCE_MD } from "./skill-content/wireframe.js";
+export { VISUAL_RECAP_SKILL_MD };
+export const RECAP_REFERENCE_FILES = {
+    "references/wireframe.md": WIREFRAME_REFERENCE_MD,
+    "references/connection.md": CONNECTION_REFERENCE_MD,
+    "references/local-files.md": LOCAL_FILES_REFERENCE_MD,
+};
+//# sourceMappingURL=skill-content.js.map

package/dist/skill-content.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"skill-content.js","sourceRoot":"","sources":["../src/skill-content.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAEtE,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAEjC,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,yBAAyB,EAAE,sBAAsB;IACjD,0BAA0B,EAAE,uBAAuB;IACnD,2BAA2B,EAAE,wBAAwB;CACtD,CAAC","sourcesContent":["import { CONNECTION_REFERENCE_MD } from \"./skill-content/connection.js\";\nimport { LOCAL_FILES_REFERENCE_MD } from \"./skill-content/local-files.js\";\nimport { VISUAL_RECAP_SKILL_MD } from \"./skill-content/visual-recap-skill.js\";\nimport { WIREFRAME_REFERENCE_MD } from \"./skill-content/wireframe.js\";\n\nexport { VISUAL_RECAP_SKILL_MD };\n\nexport const RECAP_REFERENCE_FILES = {\n \"references/wireframe.md\": WIREFRAME_REFERENCE_MD,\n \"references/connection.md\": CONNECTION_REFERENCE_MD,\n \"references/local-files.md\": LOCAL_FILES_REFERENCE_MD,\n};\n"]}

package/package.json ADDED Viewed

@@ -0,0 +1,50 @@
+{
+  "name": "@agent-native/recap-cli",
+  "version": "0.1.0",
+  "description": "Dependency-light PR visual recap CLI for Agent-Native workflows.",
+  "homepage": "https://github.com/BuilderIO/agent-native#readme",
+  "bugs": {
+    "url": "https://github.com/BuilderIO/agent-native/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BuilderIO/agent-native",
+    "directory": "packages/recap-cli"
+  },
+  "bin": {
+    "agent-native": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run --passWithNoTests",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "typescript-7": "catalog:",
+    "vitest": "catalog:"
+  },
+  "optionalDependencies": {
+    "@playwright/test": "^1.61.1",
+    "playwright": "^1.61.1"
+  },
+  "engines": {
+    "node": ">=22.22.0"
+  }
+}