@zaip-ai/cli 6.3.0 → 7.5.0

package/templates/.agents/design/design-system-maker/frontend/ADAPTATION.md

@@ -0,0 +1,351 @@
+# Maker frontend adaptation — Task5
+
+Bounded frontend phase of TASK-2026-10-11-19-27-VISUAL-MAKER-APP-V64RAF5,
+CHG-2026-10-11-19-27-VISUAL-MAKER-APP-V64RAF5 and
+EXEC-2026-10-11-19-27-VISUAL-WORKFLOWS-V64RAF01.
+Run: RUN-2026-10-11-23-30-SUBAGENT-AGENT-FRONTEND-TGTNT96ELB.
+Parent: RUN-2026-10-11-22-59-SUBAGENT-AGENT-ORCHESTRATOR-CBNWKBGFR9.
+Requested configuration: gpt-6.1-sol/high. Effective configuration: gpt-6.1-sol/high
+observed by the authorized host and relayed with the rich Start, not inferred from a prompt.
+Decision: DEC-AI-2026-10-11-23-33-MAKER-UI-6ASXZNVTB4.
+
+## Source and adaptation boundaries
+
+The authorized host read the original catalog/viewer/generate HTML, CSS and JS and
+relayed their structure, labels and measured source values. This worker did not read
+the sibling source, copy its bytes, run its scripts or verify an upstream license.
+The existing NOTICE and SOURCE-PROVENANCE remain the runtime author's records.
+No source screenshot was available for this worker; pixel fidelity is unavailable.
+
+The adaptation preserves the relayed catalog topbar, search toolbar, card grid,
+Viewer sidebar/hero/panel composition and generation form/job layout. Local semantic
+CSS variables retain the source navy background, cyan accent, radial glow and density.
+The central DESIGN.md was read. Source appearance has explicit local priority;
+central focus color, accessible 44px actions, 24px card radius, keyboard access,
+labels, semantic states and responsive layouts follow its applicable guidance.
+The slightly brighter muted text improves readability relative to the relayed opacity.
+Geist was not available offline; operational Inter/system-ui fallbacks are declared.
+No remote fonts or claim of exact typography. No logo is recreated as an asset.
+
+The new runtime has a static evidence model: the Viewer displays candidates,
+components, source/capabilities, uncertainty and Markdown as data. Legacy typography
+previews, quality scoring and arbitrary reference HTML/CSS are not executed.
+All rendered source text uses textContent; extracted colors alone use a bounded
+hex-only backgroundColor. Only a verified PNG from the local API can be an image.
+Provider/noReuse/localBrowserProxy/noLlmRetry controls are removed. Generation uses
+url/name and, for re-extraction, stable id plus the current expected_revision.
+The saved URL is sanitized; the form explicitly asks the user to check its address
+before extracting again. It does not imply exact replay of stripped queries/redirects.
+
+## Literal inventory and public component contracts
+
+All changes are new files inside `.agents/design/design-system-maker/frontend/`:
+
+- `catalog/index.html`, `catalog/index.js`: catalog orchestration and managed entry.
+- `viewer/index.html`, `viewer/index.js`: selected output, request cancellation and history.
+- `generate.html`, `generate.js`: session setup, form submission and job polling.
+- `shared/api.js`: request/connect/detail/job/generate, ApiError and CollectionPager.
+- `shared/model.js`: labels/statusLabel/known/swatches/matches/coverage,
+  entryPath/viewerPath/revisionParam.
+- `shared/components.js`: el/action/button/badge/empty/colorCandidates,
+  extractionCard/outputItem/section/dataSection/artifactActions.
+- `shared/viewer-detail.js`: renderDetail(value, callbacks and target DOM containers).
+- `shared/frontend.test.mjs`: deterministic API/model/text-node fixtures, no real browser.
+- `styles/maker.css`: local CSS entry importing base.css and layout.css.
+- `styles/base.css`, `styles/layout.css`: shared local styles and responsive compositions.
+- `ADAPTATION.md`: this handoff.
+
+The HTML entries use absolute managed asset URLs; all module imports are relative.
+There is no bundler or runtime dependency. Browser ES modules are the served frontend
+artifact, compatible with the runtime's existing catalog/viewer/generate/shared/styles
+routes and its external-script CSP. Root catalog paths and trailing-slash Viewer URLs
+work without inferring the sibling folder or a fixed port.
+
+## Data shapes, actions and states
+
+Catalog/Viewer read `{extracts,total,offset,limit,next_offset}` with limit100.
+CollectionPager serializes concurrent load-more requests, retains existing items on
+failed pages and exposes the next page. Search matches name/slug/host/theme/archetype
+and inferred hex color; coverage always identifies loaded/total and explicitly limits
+search to loaded entries. Empty, no-match, loading and retry states are separate.
+
+Viewer reads `{summary,tokens,quality,designMd,revisions,revision_count,...entry}`.
+Selection is `?id=...&revision=N`; omitting revision means current. Back/forward,
+historical revision selection and return-to-current use those same paths. Requests
+carry AbortSignal and identity guards; clearing selection also clears request identity
+as a preventive measure, not a reproduced historical bug. History requests use
+history_offset and history_limit20; older pages remain reachable beyond20. A changed
+revision count requests a current refresh rather than merging inconsistent ranges.
+Detail loading/error feedback and collection retry are independent. Revision navigation
+moves keyboard focus to the main output; history paging restores a meaningful control.
+
+The Viewer exposes collecting/partial/ready/failed, interrupted error text, null theme
+and archetype as unknown, and quality/grade/score as unscored. The revision label
+always distinguishes historical/current. DESIGN.md and proposal JSON links are
+constructed from a validated ID and viewed revision, never an arbitrary response URL.
+Screenshot requires screenshot_verified=true and a local revision PNG endpoint; failure
+shows an explicit unavailable state. Ready is not rendered-fidelity approval.
+
+Generation keeps the GET `/api/session` nonce in module memory only. POST body is
+exactly url/name/id/expected_revision and sends X-Maker-Nonce, same origin.
+Re-extraction loads current detail independently of the Viewer revision. Fields are
+disabled while submitting/polling; queued/running poll every1200ms until completed/failed.
+403 and409 require explicit session reconnect/current revision reload;429 permits
+manual retry. Poll network failure keeps the accepted operation's identity and offers
+resume monitoring, without automatically issuing a duplicate POST. Leaving the page
+stops polling; no localStorage/sessionStorage or persisted nonce/job dataset is added.
+
+## Focused verification and limits
+
+Observed environment: Node v22.16.0, Windows. Checks performed in this phase:
+
+- `node --test .agents/design/design-system-maker/frontend/shared/frontend.test.mjs`:
+  five tests passed, zero failed; tool-output `616077`. Controlled fetch and text-node
+  fixtures cover item101, concurrent load-more/retry, bounded candidates/unknowns,
+  whitelisted mutation/nonce, historical API paths and hostile text/local artifact URLs.
+  They do not prove transport, browser pixels or keyboard behavior in a real browser.
+- `node node_modules/@biomejs/biome/bin/biome check --write .agents/design/design-system-maker/frontend`:
+  final pass,14 checked files, test formatting only; tool-output `5ab007`.
+  One narrow HTML lint exception permits keyboard focus on the scrollable log region.
+- Final read-only Biome check:14 files, no fixes, passed; tool-output `f4a6f0`.
+  `node --check` passed for catalog/index.js, viewer/index.js and generate.js;
+  outputs `f2d26f`, `58c61c`, `5ab9cd`. Source line inventory `561248` confirms
+  every module below400 lines (largest stylesheet308).
+- Production-source search found no innerHTML, storage, frames or legacy controls;
+  output `824f1e`. Literal Git status with the host-recommended configuration flags
+  was hook-blocked as a configuration override; no retry or policy change. The
+  literal inventory above reflects the files created by this worker, not Git approval.
+- Initial local test errors were fixture-only: unavailable Node22 mock.property API,
+  corrected to an explicit restored document descriptor. A markup mirror check was
+  removed to retain behavior-focused testing. No product failure was inferred.
+
+Real served interactions, screenshots, Node24 candidate qualification and consumer
+integration are pending the authorized final integration phase. No source screenshot
+comparison, complete accessibility audit or fidelity approval is claimed. This phase
+does not approve or complete Task5, register lifecycle state, commit or publish.
+Runtime/data/provenance/NOTICE/EXE/harness and central catalog were not edited.
+
+## Handoff to Manu and Leo
+
+Manu: represent these local UI contracts in `#/components` using the current central
+identity, with stable fixtures and the existing catalog boundary. Native DOM helpers
+may be rendered through a small adapter where valid; do not import this product's
+CSS as central tokens or move API/polling/collection logic into the central catalog.
+Needed states: catalog card partial/ready/failed; unknown quality/theme; inferred colors;
+sidebar selected/focus; revision current/historical; empty/loading/retry; form validation,
+disabled/generation queued/running/completed/failed and interrupted log. Include narrow
+layout and keyboard/focus. The worker cannot write the central representation.
+
+Leo: exercise the actual served routes and API against the authorized two URL fixtures,
+observe catalog→Viewer identity, current/historical revisions, return-current, exports,
+generation→job→output, reload/restart persistence and pending/failure states. Record
+actual origin/viewport/candidate/screenshot bytes using the existing canonical bounded
+mechanism; inspect responsive desktop and narrow layout and keyboard access. Preserve
+literal stable test IDs (`catalogSearch`, `catalogGrid`, `viewerSearch`, `viewerList`,
+`viewerHero`, `viewerPanel`, `generateForm`, `jobStatus`, `jobResult`, `jobLog`).
+This handoff adds no authorization for source runners, private datasets, external
+publication or OS restart/shutdown/suspend/hibernate/logoff.
+
+## v6.4 structural repair delta — 2026-10-12
+
+This section describes the current Task10 maintenance increment; the Task5 record
+above remains historical. Ownership stays exclusively in this frontend directory.
+The host observed gpt-6.1-sol/high for native turn
+01a13213-3708-72d1-bf9a-4d0b092dcbf7; no new Run binding was fabricated.
+
+Original catalog/viewer CSS and preview source were inspected read-only, along
+with the host's Zaip, AIOX, diagnostic and failed403 screenshots. The independent
+implementation restores item-specific catalog/sidebar themes and applies the
+selected item's normalized model to the whole Viewer. It resets that model on
+loading, failed selection, deletion and trash navigation. Items without a model
+retain an isolated Maker fallback rather than inheriting the selected item's theme.
+Current extracted tokens prevail over old screenshots; no Poppins/cyan values are
+forced onto current Manrope/Sora data. NOTICE and source provenance were preserved.
+
+Managed routes `/viewer/preview.html?id=ID&revision=N` and
+`/viewer/diagnostic.html?id=ID&revision=N` render our own native DOM. Preview contains
+primary/secondary/ghost/disabled buttons, labeled input/select, cards/badges/navigation,
+surfaces, Aa font/size specimens and spacing/radius/shadow samples. Component
+descriptors may supply allowlisted local scalar styles. Diagnostic retains full
+report tables, every reported color, provenance, raw/export links and persisted
+metric numerators/denominators. Coverage remains extraction coverage, not a visual
+quality grade; the formula and older recorded scores are unchanged.
+
+The sole consumed model is `summary/detail.visual_model`, schema1,
+`declared-semantic-v1`, inferred or unavailable. Colors, font-family names,
+dimensions and normalized shadows are validated again before application.
+No remote stylesheet, source HTML, font URL or script is applied. Declared font
+families use installed fonts or system fallback; exact typography is not proved.
+Missing semantic colors use explicit local demonstration fallbacks. Shell font size
+has a12px minimum. Inference, fallback and absent fontfaces/motion/stack/accessibility
+proof are collected under the collapsed “Método e limites”. Complete AA, active
+source cascade and pixel parity remain unclaimed. Dedicated border-scale rendering
+is not added; border tokens can appear on native controls and component descriptors.
+
+Failed collection, collecting and genuinely missing legacy reports are distinct.
+HTTP403 is presented as a collection block, including preserved older HTTP error
+text, with explicit open-source-URL/edit-target actions. No automatic retry,
+challenge bypass or assisted-capture capability is advertised. Existing loading,
+reprocess, recoverable trash, pagination and revision-history contracts remain.
+Old saved models are projected by the backend; bounded local detail hydration is
+used only when a summary lacks a model, without re-extracting or writing records.
+
+Literal modified files in this increment:
+
+- `catalog/index.js`, `viewer/index.js`, `styles/maker.css`.
+- `shared/components.js`, `shared/frontend.test.mjs`, `shared/job-view.js`,
+  `shared/model.js`, `shared/report-view.js`, `shared/viewer-detail.js`.
+- `ADAPTATION.md` (this appended delta).
+
+Literal new files in this increment:
+
+- `shared/visual-model.js`, `shared/extraction-state.js`, `shared/failure-view.js`,
+  `shared/model-hydration.js`, `shared/specimens.js`, `shared/preview.test.mjs`.
+- `styles/specimens.css`, `viewer/preview.html`, `viewer/diagnostic.html`,
+  `viewer/specimen.js`.
+
+Stable browser contracts: “Preview render”, “Abrir diagnóstico”,
+`data-specimen=button-primary/input/select`, `data-report-section=coverage`,
+body `.ds-applied`/`data-ds-theme`, and `--ds-background/foreground/primary/font/heading-font`.
+Existing `#viewerHero`, `#viewerStatus`, `#sourceUrl`, `#generateSubmit` remain.
+Native specimens have local feedback only; no collection API mutation is introduced.
+
+Focused source verification:13/13 Node tests passed after the final source changes
+(tool4aa9fb); Biome3 changed files passed (a90758), after the earlier28-file pass
+(71547f). Syntax checks734412/870216 and earlier scoped diff check6d0471 passed.
+The host independently reported three real browser scenarios with zero page errors
+(d96e64). Its pixel inspection found light status/placeholder contrast, fallback
+sidebar inheritance and a diagnostic self-link; this final source increment fixes
+only those findings. The host owns the final screenshot recheck, combined review,
+manifest/build and human-ready qualification. No release/publication approval,
+complete accessibility audit or source pixel-parity approval is issued here.
+
+## Browser opt-in and original diagnostic shell — current maintenance delta
+
+The generation form now offers explicit browser mode when the session reports
+`capabilities.browser.available` with method `local-isolated-cdp`. HTTP stays the
+default. Browser requests preserve the exact safe URL, revision guards and nonce.
+The backend opens its own isolated window; UI displays observed browser-open/wait/
+capture phases, human action and deadline. Cancel targets only the accepted browser
+job using its returned collecting revision; terminal cancellation is failed with
+`failure.kind=cancelled`. No popup, browser launch, network probe or CAPTCHA automation
+was performed by this frontend worker. Real exact-URL/browser validation belongs to
+the host, and source tests do not prove challenge completion.
+
+The read-only reference `_ref/zaip-design-system-maker/app/lib/preview.cjs` and saved
+`_outputs/zaip/preview.html` informed the restored white diagnostic layout: header
+identity, DESIGN.md preview title, black borders/offset shadows, score-category tiles,
+colors, live native examples, type/scales, raw DESIGN.md and technical details.
+Attribution for the adapted original presentation: Alan Nicolas (@oalanicolas),
+design-md / ZAIP Design System Maker, MIT license (declared in reference preview.cjs;
+existing project NOTICE is preserved). This frontend appendix records that attribution;
+it does not alter or independently certify the upstream license/NOTICE records.
+Remote styles/scripts/generated HTML from that reference are not executed or embedded.
+Tiles now use the derived Design Score described in the final appendix, never a copied grade76.
+Unmeasured original sections remain explicitly unavailable. The diagnostic shell stays
+neutral white; extracted safe tokens apply only inside its native examples.
+
+Site icons are square, using `visual.faviconStatus=verified` and a locally constructed
+`/api/extracts/:id/favicon?revision=N`; accepted raster/ICO bytes are the backend's
+verification responsibility. Missing or failed images fall back to initials. No source
+favicon URL is loaded remotely. Catalog, sidebar and native card examples share this
+same component.
+
+Changed in this delta: `generate.html`, `generate.js`, `shared/api.js`,
+`shared/job-view.js`, `shared/failure-view.js`, `shared/frontend.test.mjs`,
+`shared/model.js`, `shared/components.js`, `shared/specimens.js`,
+`shared/preview.test.mjs`, `viewer/diagnostic.html`, `viewer/specimen.js`,
+`styles/layout.css`, `styles/specimens.css`, and this appendix. New files:
+`shared/diagnostic-view.js`, `styles/diagnostic.css`.
+Stable added selectors: `#browserMode`, `#browserAvailability`, `#jobCancel`,
+`.diagnostic-original-page`, `[data-diagnostic-metric]`, `[data-site-icon]`.
+Routes and previous selectors remain unchanged.
+
+Focused Node tests15/15 passed (fc6033), including the single browser contract fixture
+and persisted diagnostic/favicon behavior. Initial Biome16-file pass27d1f7 had one
+descending-specificity warning; its selector was corrected in the final CSS pass.
+Host visual/EXE/exact-source proof and review remain separate, pending integration.
+Requested model/effort: gpt-6.1-sol/high; this new maintenance turn's effective
+configuration has not been observed by this worker and is unavailable.
+# Compact details (2026-10-13)
+
+The details page keeps the selected visual model, a prominent Design Score
+with grade, deduplicated color samples and the verified screenshot. Its three
+primary links are DESIGN.md, Preview Render and Abrir Diagnóstico Completo.
+Reprocess and recoverable trash controls occupy a separate top toolbar with icons.
+Native details/summary disclosures contain interactive specimens, typography,
+scales and revision history. Complete tables and provenance stay in the white
+diagnostic. This native Maker surface is its own renderable component specimen;
+it does not introduce a cross-product React dependency or central design tokens.
+
+New DESIGN.md exports group distinct token values by property. Existing revisions
+offer the same compact read-only projection via `design?revision=N&format=compact`;
+their original bytes remain available without that parameter. Full observations
+and limitations remain in the verified proposal/report artifacts.
+# Captured theme correction
+
+Viewer and render preview use each selected reference's saved computed styles across
+the header, actions, score bars, surfaces and native specimens. Neutral missing-role
+fallbacks replace the old blue default. Changing references replaces all theme variables,
+including control radius. Captured-role colors are distinct from the complete declared
+CSS inventory in the diagnostic. No remote recollection or historical artifact rewrite.
+
+# Design Score and compact catalog (2026-10-13)
+
+Catalog cards show square local favicon, title/domain, success/failure badge, Design
+Score letter/number, up to eight color dots and Details/Preview actions. UUIDs,
+revision counters, sampling paragraphs and instructional filler moved out of cards.
+The viewer repeats the same score with seven graded bars; the white diagnostic has
+large overall grade, category tiles with observed/ideal values, criterion disclosures
+and a semantic contrast table. Technical extraction coverage stays in its disclosure.
+
+The additive `design_score` presentation projection is computed by
+`tools/visual-url/design-score.mjs` from saved evidence; it never changes historical
+artifact bytes. It adapts reference `lib/design-md.cjs` count heuristics while fixing
+unreachable scale branches, replacing unavailable confidence with explicit CSS-variable
+adoption. Version 2 runs the local visual-token lint and includes its result in the
+average. The diagnostic lists executed rules and findings; unavailable models still
+show N/A. It does not claim to run the remote site's lint or Google's linter. The method and limits
+are documented in API.md; these scores must not be presented as the original algorithm
+or a complete accessibility audit. Existing historical paragraphs describing unscored
+presentation are superseded by this appendix.
+
+Version 3 labels CSS-variable adoption `Tokenização da origem`, accepts whitespace
+inside `var()` and preserves the visual-declaration denominator. Generated token quality
+is a separate diagnostic section, excluded from the seven-category average. Both the
+current DESIGN.md projection and diagnostic derive from `generated-tokens-v1`, with
+coverage, integrity, evidence and component-mapping denominators exposed. Historical
+original exports remain immutable. API.md defines weights and limitations.
+
+Catalog theme scope also covers hover/focus, metadata typography and badge shape.
+Primary control family/weight are projected from the same saved captured control as
+its color/radius, with body typography fallback. Cards label their applied preview
+theme `dark`/`light`, including neutral fallback surfaces when source theme is unknown;
+this is not a new assertion about the remote site's active theme. Reference IDs are
+shown only in the details history. Fonts still depend on locally available font files.
+
+The catalog search targets name, site URL/host and full or short ID (including #001).
+Separate theme and color filters combine with the search. Theme follows the applied
+card badge; unavailable models do not match a specific theme. Color checkboxes use
+OR within the selected families and the same eight swatches rendered on the card,
+not all colors found in remote CSS. Fixed hue families provide red, orange, yellow,
+green, cyan, blue, purple, pink, brown and neutral black/gray/white; classification is
+approximate and mostly transparent swatches are excluded. Filters cover loaded pages
+and remain active while loading more. Native select/details/checkbox controls support
+keyboard operation, Escape/outside dismissal, reset, empty results and mobile widths.
+
+Reprocessing stays in the viewer through a native progress dialog. Completion closes
+the dialog and refreshes the selected revision and sidebar without navigating to the
+generation form. Hiding the dialog keeps monitoring active; failures remain explicit.
+Polling and refresh retries resume the same operation without submitting a second
+extraction. Missing replay URLs offer an explicit link to the generation form.
+
+Reprocessing now preserves browser collection from recent history (up to 100
+revisions), recovering browser evidence after intervening HTTP-only retries. The
+bounded snapshot includes html/body and visible headings/controls/text with unique
+DOM paths, border and shadow properties. Component mappings use their own captured
+styles; repeated legacy selectors remain unmapped. Poor-contrast primary controls
+remain measurable instead of being excluded. DESIGN.md includes the same supported
+contrast pairs as the diagnostic, with evidence and explicit unavailable cases.
+Source CSS-variable adoption and generated token quality remain separate, with
+unchanged score weights and no substitution of invented colors to pass contrast.

package/templates/.agents/design/design-system-maker/frontend/MAKER-REPAIR-HANDOFF.md

@@ -0,0 +1,134 @@
+# Maker measured-report UI repair
+
+Task: TASK-2026-10-11-19-27-VISUAL-RELEASE-V64RAF10, executing revision19/attempt3.
+Run: RUN-2026-10-12-15-57-SUBAGENT-AGENT-FRONTEND-T7MGZ3R9ZL.
+Parent: RUN-2026-10-12-15-31-SUBAGENT-AGENT-ORCHESTRATOR-3S5CBGXYSM.
+Observed active turn: 01a13175-4fbc-7653-8898-3db3706eeaa8.
+Requested and host-observed effective configuration: gpt-6.1-sol/high, unchanged.
+Recorded at2026-10-12T16:19:24.9007713-03:00; this is recording time, not an invented
+timestamp for each check. The host has the native command observations.
+
+This phase began readonly. GO UI arrived only after the backend phase was terminal,
+the canonical build manifest was updated and the root confirmed authenticated stop
+of the old service. No source writes preceded GO. This worker did not start or stop
+a live service, access a sibling source, mutate project data, spawn a child, write
+lifecycle, stage/commit/publish or invoke host power/session actions.
+
+## Delivered behavior
+
+The existing catalog/Viewer/generate identity and navigation remain the product UI.
+New report presentation consumes the frozen API contract in API.md and the runtime
+handoff `.local/maker-repair-runtime-handoff.json`; it does not calculate a replacement
+backend score or hardcode live brand/font/color/element/sample counts.
+
+- Catalog shows persisted extraction-coverage score and global CSS sample counts.
+  Its12-color summary remains explicitly a preview; the full Viewer report renders
+  **every** report.colors row in its original order, with normalized hex-only chips,
+  occurrence counts and expandable source/evidence data.
+- Viewer report is legible sections/tables: persisted score, metric numerator and
+  denominator, ratio, weight, explanation and formula; global sampling; typography
+  with distinct property names; spacing; radii; grouped static interface candidates;
+  resources and timestamps/hashes; gaps and limits. Per-source CSS counts are labeled
+  before global aggregation. No JSON dump is used as the main report interface.
+- HTML inventory is labeled ELEMENTOS HTML and explicitly includes metadata. Static
+  candidate groups are separately counted and are not presented as proven reusable
+  components. Font names are report text; no extracted fonts/CSS are applied to the UI.
+- Markdown and JSON report exports use local revision API paths. DESIGN.md remains
+  escaped plain text. Legacy revisions explicitly have no report or retrospective
+  score. Browser cascade/theme, visual/LLM/AA quality and central promotion remain
+  unassessed by this static evidence method.
+- Request target and final redacted URL are separately displayed. One-click reprocess
+  fetches the current revision and sends only expected_revision to the reprocess
+  endpoint, retaining the exact safe saved request URL server-side. Missing replay
+  URL routes to an explicit input form with no sanitized-display-URL reconstruction.
+  The explicit reprocess form sends expected_revision and a user-visible safe URL;
+  existing ID/name and history are preserved by the API contract.
+- Generation adds HTTPS to protocol-less input visibly, retains API destination
+  validation, and shows a spinner/disables duplicate submissions synchronously before
+  awaiting POST. Polls show actual phase/event/resource/duration/start/end values.
+  Completion says Relatório gerado; CSS amostrado and browser limits are separate.
+  No percentage or artificial time/phase is generated. Unknown terminal historical
+  phase/time stays explicit: status wins, and its inconsistent last phase is shown.
+  Lost polling offers resume without duplicate POST; unconfirmed submission warns
+  that the server may have accepted it and requires manual preparation before retry.
+- Viewer has a paginated recoverable trash collection. Moving an item fetches current
+  metadata, asks for native confirmation and sends both revision guards. Restore asks
+  for confirmation and sends the retained summary guards, without source fetch.
+  The restored-history link points to the normal Viewer. Stale403/409 feedback is
+  explicit; no mutation is automatically repeated.
+
+All source content uses textContent or escaped pre text. Only bounded hex values
+become swatch CSS; exports and screenshots use validated local IDs/revisions.
+Source provenance URLs remain text, never active external HTML/CSS. Nonces stay in
+memory and every POST/DELETE uses the existing Host/Origin/nonce contract.
+
+## Literal inventory
+
+Modified existing files, exclusively under this frontend:
+
+- catalog/index.html
+- generate.html
+- generate.js
+- shared/api.js
+- shared/components.js
+- shared/frontend.test.mjs
+- shared/model.js
+- shared/viewer-detail.js
+- styles/maker.css
+- viewer/index.js
+
+New files:
+
+- shared/job-view.js
+- shared/report-view.js
+- shared/viewer-actions.js
+- styles/report.css
+- MAKER-REPAIR-HANDOFF.md
+
+No runtime/tool/calculation/data/build/EXE/central/catalog/fixture file was modified
+by this worker. The older ADAPTATION.md describes the initial implementation; this
+handoff supersedes its always-unscored and sanitized-replay presentation descriptions.
+
+## Focused checks and honest limits
+
+- `node --test .agents/design/design-system-maker/frontend/shared/frontend.test.mjs`:
+ 9/9passed, tool-output382292. Existing paging/history/text security tests plus
+  HTTPS validation, exact reprocess body, DELETE/restore guards and memory nonce,
+  paginated trash, all30 synthetic report colors and typed data/text/exports, and
+  honest terminal status/legacy phase mismatch. Mock transport/text-node fixtures
+  do not claim real browser rendering or data persistence.
+- Final Biome check on the literal production directories/files listed in the tool
+  command:18 files, no fixes, passed0d66c5. Earlier focused formatting only changed
+  owned frontend sources. Largest source module324lines, report renderer239lines;
+  source inventory e228e5, below400 warning threshold.
+- `node --check` for generate.js/viewer/index.js/shared/viewer-actions.js:
+  passed935101/9d1a11/067159. Shared report/model/API/job modules are also parsed by
+  the direct Node tests. No unrelated release suite or duplicate browser harness.
+- `git diff --check -- .agents/design/design-system-maker/frontend`: passed7257e9.
+  Literal source inventory from scoped Git status dd4a90, plus this new handoff.
+
+No actual service/API mutations or screenshots were exercised in this phase. The
+CSS supports390/1440 widths and keyboard-focusable overflow regions, but actual
+layout, focus, confirmation handling and full AA remain browser-validation pending.
+Central specimen/catalog representation was outside this worker's scope and was
+not revalidated here. No Task completion, release gate, human readiness approval or
+publication is asserted.
+
+## Immediate integration handoff
+
+Selectors preserved: #sourceUrl, #generateSubmit, #jobStatus, #jobLog, #jobResult,
+#viewerHero, #viewerPanel, #viewerSearch/#viewerList, #catalogSearch/#catalogGrid.
+New selectors: #jobSpinner, #jobDetails, [data-report-color],
+[data-report-section=coverage|colors|elements], [data-action=reprocess|trash|restore],
+[data-trash-id]. Trash route is `/viewer/?collection=trash`.
+
+Leo first repairs the known backend restart-reconciliation phase/time P2, with the
+same API shapes, after this frontend phase is terminal. Root then refreshes the
+canonical source manifest and starts the authenticated EXE/runtime. Validate actual
+create→job→report, stored coverage/formula/all colors/fonts/sample/HTML labels,
+exports, exact safe replay/history and390/1440 layout. Confirm native dialogs in the
+browser harness. DELETE only a synthetic test item and restore it; preserve both
+existing user entries and their immutable revisions. Capture and examine real
+screenshots against the independent baseline; the baseline is not a product asset.
+Notify the user when ready for human testing. Publication remains unauthorized until
+later explicit human approval; this handoff does not consume or bypass that gate.

package/templates/.agents/design/design-system-maker/frontend/advanced/examples.js

@@ -0,0 +1,30 @@
+export function examples(origin, code = "001") {
+  if (!/^http:\/\/127\.0\.0\.1:\d+$/.test(origin) || !/^\d{3,16}$/.test(code))
+    throw new Error("Endereço local ou código inválido");
+  const listing = `$origem = '${origin}'
+$designs = @()
+$offset = 0
+do {
+  $pagina = Invoke-RestMethod "$origem/api/extracts?offset=$offset&limit=100"
+  $designs += $pagina.extracts
+  $offset = $pagina.next_offset
+} while ($null -ne $offset)`;
+  return {
+    agentExample: `Use o design #${code} da coleção local em ${origin}. Consulte GET /api/extracts, seguindo next_offset até encontrar design_code "${code}". Use o id completo e a revisão retornados para obter /api/extracts/:id/design?revision=N&format=compact. Aplique esse design à tarefa e informe o código e a revisão utilizados. Se não conseguir acessar a API local, peça o arquivo DESIGN.md; não escolha outra referência.`,
+    listExample: `${listing}
+$designs | Select-Object design_code, name, id, revision`,
+    designExample: `${listing}
+$codigo = '${code}'
+$item = $designs | Where-Object { $_.design_code -eq $codigo } | Select-Object -First 1
+if ($null -eq $item) { throw "Design #$codigo não encontrado na coleção ativa." }
+$designMd = Invoke-RestMethod "$origem/api/extracts/$($item.id)/design?revision=$($item.revision)&format=compact"
+$designMd`,
+    generateExample: `$origem = '${origin}'
+$sessao = Invoke-RestMethod "$origem/api/session"
+$headers = @{ Origin = $origem; 'X-Maker-Nonce' = $sessao.nonce }
+$corpo = @{ url = 'https://example.com/'; mode = 'http' } | ConvertTo-Json
+$job = Invoke-RestMethod "$origem/api/generate" -Method Post -Headers $headers -ContentType 'application/json' -Body $corpo
+# Consulte novamente enquanto o status for queued ou running:
+Invoke-RestMethod "$origem/api/jobs/$($job.id)"`,
+  };
+}

package/templates/.agents/design/design-system-maker/frontend/advanced/index.html

@@ -0,0 +1,75 @@
+<!doctype html>
+<html lang="pt-BR">
+<head><link rel="icon" type="image/png" href="/assets/zaip-icon.png">
+  <meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>API e integrações · Zaip Design System Maker</title>
+  <link rel="stylesheet" href="/styles/maker.css"><link rel="stylesheet" href="/styles/advanced.css">
+  <script type="module" src="/advanced/index.js"></script>
+</head>
+<body class="advanced-page">
+  <a class="skip-link" href="#advancedMain">Pular para as instruções</a>
+  <header class="ds-topbar"><a class="advanced-brand" href="/catalog/">Zaip Design System Maker</a><nav aria-label="Navegação principal"><a class="action" href="/catalog/">Voltar ao catálogo</a></nav></header>
+  <main id="advancedMain" class="advanced-main">
+    <section class="advanced-hero">
+      <p class="kicker">Avançado</p><h1>API e integrações</h1>
+      <p>Use seus designs em agentes, scripts e ferramentas locais. Consulte a coleção, encontre uma referência pelo código e obtenha seu DESIGN.md sem navegar pelos cards.</p>
+      <p class="muted">Para criar e consultar designs pela interface, continue usando o catálogo. Esta área é opcional.</p>
+      <div class="advanced-connection"><span>Endereço desta sessão</span><code id="apiOrigin">O endereço será preenchido ao abrir esta página no Maker.</code></div>
+      <p class="help">Mantenha o Maker aberto. O endereço e a porta podem mudar ao iniciá-lo novamente; volte aqui para copiar exemplos atualizados.</p>
+      <div class="page-actions"><a class="action primary" href="/api/extracts">Abrir coleção em JSON</a><a class="action" href="#examples">Ver exemplos</a></div>
+    </section>
+
+    <section class="advanced-section" aria-labelledby="agentTitle">
+      <h2 id="agentTitle">Usar com um agente</h2>
+      <p>Informe o código exibido no card, como <strong>#001</strong>. O código identifica um design nesta coleção; referências do mesmo site têm códigos diferentes. Para fixar uma versão, informe também a revisão.</p>
+      <label for="designCode">Código para os exemplos</label><input id="designCode" value="001" placeholder="#001" inputmode="numeric" autocomplete="off" aria-describedby="codeHelp">
+      <p id="codeHelp" class="help">Substitua pelo código do seu card. Aceita 001 ou #001.</p>
+      <div class="example-heading"><h3>Instrução pronta para o agente</h3><button type="button" data-copy="agentExample">Copiar instrução</button></div>
+      <pre id="agentExample" class="advanced-code"></pre>
+      <p class="help">O agente precisa conseguir acessar este computador e a API local. Colar o endereço em um agente que roda na nuvem não estabelece essa conexão. Como alternativa, entregue o arquivo DESIGN.md ao agente.</p>
+    </section>
+
+    <section id="examples" class="advanced-section" aria-labelledby="examplesTitle">
+      <h2 id="examplesTitle">Exemplos no PowerShell</h2>
+      <p>Copie o exemplo para seu terminal. Copiar não executa comandos.</p>
+      <div class="example-heading"><h3>1. Listar os designs</h3><button type="button" data-copy="listExample">Copiar listagem</button></div>
+      <p>Consulta todas as páginas e mostra código, nome, ID e revisão.</p><pre id="listExample" class="advanced-code"></pre>
+      <div class="example-heading"><h3>2. Ler o DESIGN.md pelo código</h3><button type="button" data-copy="designExample">Copiar consulta</button></div>
+      <p>Localiza o código em toda a coleção e obtém a versão compacta da revisão encontrada. O resultado fica na variável <code>$designMd</code>; nenhum arquivo é sobrescrito.</p><pre id="designExample" class="advanced-code"></pre>
+    </section>
+
+    <section class="advanced-section" aria-labelledby="routesTitle">
+      <h2 id="routesTitle">O que a API oferece</h2>
+      <p><code>:id</code> é o identificador completo retornado pela listagem. O código curto fica no campo <code>design_code</code>, sem o #.</p>
+      <div class="advanced-table"><table><thead><tr><th>Consulta</th><th>Para que serve</th></tr></thead><tbody>
+        <tr><td><code>GET /api/extracts?offset=0&amp;limit=100</code></td><td>Designs ativos. Siga <code>next_offset</code> até ele ser nulo; limite de 1 a 100 por página.</td></tr>
+        <tr><td><code>GET /api/extracts/:id</code></td><td>Detalhes, código, Design Score, modelo visual e histórico paginado.</td></tr>
+        <tr><td><code>GET /api/extracts/:id/design?revision=N&amp;format=compact</code></td><td>DESIGN.md otimizado. Sem <code>format=compact</code>, retorna o arquivo original preservado.</td></tr>
+        <tr><td><code>GET /api/extracts/:id/proposal</code></td><td>Proposta e evidências em JSON.</td></tr>
+        <tr><td><code>GET /api/extracts/:id/report</code></td><td>Relatório de cobertura da extração; o Design Score está nos detalhes.</td></tr>
+        <tr><td><code>GET /api/extracts/:id/screenshot</code><br><code>GET /api/extracts/:id/favicon</code></td><td>Imagens locais, quando disponíveis naquela revisão.</td></tr>
+        <tr><td><code>GET /api/trash</code></td><td>Lista da lixeira, com a mesma paginação da coleção.</td></tr>
+        <tr><td><code>GET /api/jobs/:id</code></td><td>Estado de uma coleta: queued, running, completed ou failed.</td></tr>
+      </tbody></table></div>
+      <p class="help">Acrescente <code>?revision=N</code> aos detalhes ou artefatos para consultar uma revisão específica. Sem esse parâmetro, a API usa a revisão atual.</p>
+    </section>
+
+    <details class="advanced-section advanced-disclosure">
+      <summary>Automatizar uma nova coleta</summary>
+      <p>Este exemplo cria um novo design quando executado. Altere a URL antes de rodar. A API inicia uma tarefa e retorna seu ID; consulte o job até concluir. Uma resposta 202 significa que a tarefa foi aceita, não que a extração terminou.</p>
+      <div class="example-heading"><h3>Criar por URL via PowerShell</h3><button type="button" data-copy="generateExample">Copiar criação</button></div><pre id="generateExample" class="advanced-code"></pre>
+      <p>O modo <code>http</code> lê HTML e CSS. Para captura renderizada, use <code>mode = 'browser'</code> quando <code>/api/session</code> indicar <code>capabilities.browser.available = true</code>. O navegador local pode pedir sua interação.</p>
+      <p>Operações POST e DELETE exigem <code>Origin</code> igual ao endereço local e <code>X-Maker-Nonce</code> obtido em <code>GET /api/session</code>. O nonce pertence à sessão atual; obtenha-o novamente após reiniciar o Maker.</p>
+      <ul><li><code>POST /api/extracts/:id/reprocess</code>: cria nova revisão, com <code>expected_revision</code>.</li><li><code>DELETE /api/extracts/:id</code>: move para a lixeira, com <code>expected_revision</code> e <code>expected_trash_revision</code>.</li><li><code>POST /api/trash/:id/restore</code>: restaura usando as duas revisões atuais da listagem da lixeira.</li></ul>
+    </details>
+
+    <details class="advanced-section advanced-disclosure">
+      <summary>Conexão e erros comuns</summary>
+      <ul><li><strong>Conexão recusada:</strong> abra o executável e use o endereço atual mostrado nesta página.</li><li><strong>403:</strong> confira Origin e nonce. Chamadas feitas por páginas de outros sites são recusadas.</li><li><strong>404:</strong> confira o ID, a revisão e a disponibilidade do artefato; o design pode estar na lixeira.</li><li><strong>409:</strong> a revisão mudou ou já existe coleta em andamento. Consulte os detalhes antes de repetir.</li><li><strong>429:</strong> a fila está cheia. Aguarde os jobs atuais terminarem.</li></ul>
+      <p>A API atende somente em <code>127.0.0.1</code> enquanto o Maker está aberto. Ela não é um serviço público, webhook ou conector MCP. As integrações usam HTTP local; nenhum serviço externo é conectado automaticamente.</p>
+    </details>
+    <p id="copyStatus" role="status" aria-live="polite"></p>
+    <noscript>Ative JavaScript para preencher o endereço local e os exemplos copiáveis. As rotas e instruções acima continuam disponíveis.</noscript>
+  </main>
+</body>
+</html>

package/templates/.agents/design/design-system-maker/frontend/advanced/index.js

@@ -0,0 +1,30 @@
+import { examples } from "./examples.js";
+
+const code = document.querySelector("#designCode");
+const status = document.querySelector("#copyStatus");
+document.querySelector("#apiOrigin").textContent = location.origin;
+function render() {
+  const value = code.value.trim().replace(/^#/, "");
+  const valid = /^\d{1,16}$/.test(value) && /[1-9]/.test(value);
+  code.setAttribute("aria-invalid", String(!valid));
+  for (const button of document.querySelectorAll("[data-copy]")) button.disabled = !valid;
+  if (!valid) {
+    status.textContent = "Informe um código numérico, como #001.";
+    return;
+  }
+  for (const [id, text] of Object.entries(examples(location.origin, value.padStart(3, "0"))))
+    document.getElementById(id).textContent = text;
+  status.textContent = "";
+}
+code.addEventListener("input", render);
+for (const button of document.querySelectorAll("[data-copy]"))
+  button.addEventListener("click", async () => {
+    try {
+      await navigator.clipboard.writeText(document.getElementById(button.dataset.copy).textContent);
+      status.textContent = "Copiado. Nenhum comando foi executado.";
+    } catch {
+      status.textContent =
+        "Não foi possível copiar automaticamente. Selecione e copie o texto do exemplo.";
+    }
+  });
+render();