ketatlas 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.2
+
+- Show screen status, blockers, linked PR states and scoped state checks in preview footers, with direct access to progress details.
+- Keep the footer visible when scrolling, refresh it after edits, and support read-only previews.
+
 ## 0.2.1
 
 - Show compact numeric progress badges after workflow step counts, with status counts, checklist completion and blockers in tooltips.

package/README.md

@@ -17,15 +17,15 @@ https://github.com/user-attachments/assets/13f24fc8-7b8e-4bda-9e02-364c120ee163
 [KetAtlas is available on npm](https://www.npmjs.com/package/ketatlas). Use Node.js 22+ and run it from any directory:
 
 ```sh
-npx --yes ketatlas@0.2.1 scaffold my-atlas --template web
-npx --yes ketatlas@0.2.1 serve my-atlas/atlas.json
-npx --yes ketatlas@0.2.1 audit my-atlas/atlas.json --strict
+npx --yes ketatlas@0.2.2 scaffold my-atlas --template web
+npx --yes ketatlas@0.2.2 serve my-atlas/atlas.json
+npx --yes ketatlas@0.2.2 audit my-atlas/atlas.json --strict
 ```
 
 Or install the CLI once for your user account:
 
 ```sh
-npm install --global ketatlas@0.2.1
+npm install --global ketatlas@0.2.2
 ketatlas scaffold my-atlas
 ketatlas serve my-atlas/atlas.json
 ketatlas audit my-atlas/atlas.json --strict

package/docs/progress.md

@@ -2,6 +2,8 @@
 
 Open **Screens** to review delivery across the project. Counts use unique screen IDs, not repeated workflow nodes. Filter by status, workflow, blocker, or search names, IDs, tasks and owners. **View in map** focuses a screen; **Screen progress** opens its record from the node inspector. Mockup badges remain separate from implementation status.
 
+Screen and state preview footers show the shared screen status, blockers and linked PRs with their recorded states. **Progress details** opens the same screen record. State-specific acceptance counts appear only when checks explicitly reference the previewed workflow/node; the shared screen status is not a separate claim that a state has been verified. Missing evidence displays **No linked PRs**. The footer stays visible while scrolling and updates after a save.
+
 ## Sidebar and project completion
 
 Project-wide verified/checklist percentages and blocker counts appear in the top bar beside **Screens**. The sidebar shows one compact numeric badge after each workflow’s step count (`2 steps [30%]`). **Verified %** is the number of Verified screens divided by the total unique screens in that scope. Repeated nodes and error variants count once; note/external nodes do not count. Screenless flows have no badge. Percentages round down so unfinished work cannot appear as 100%.
@@ -69,11 +71,11 @@ Evidence kinds are `pr`, `test`, `release`, `reference`. Required fields: `id`,
 ## Editing locally and from agents
 
 ```sh
-npx --yes ketatlas@0.2.1 serve atlas.json
-npx --yes ketatlas@0.2.1 serve atlas.json --read-only
-npx --yes ketatlas@0.2.1 progress atlas.json --init
-npx --yes ketatlas@0.2.1 progress atlas.json --json
-npx --yes ketatlas@0.2.1 progress atlas.json --set sign-in --record record.json --expect REVISION_FROM_READ
+npx --yes ketatlas@0.2.2 serve atlas.json
+npx --yes ketatlas@0.2.2 serve atlas.json --read-only
+npx --yes ketatlas@0.2.2 progress atlas.json --init
+npx --yes ketatlas@0.2.2 progress atlas.json --json
+npx --yes ketatlas@0.2.2 progress atlas.json --set sign-in --record record.json --expect REVISION_FROM_READ
 ```
 
 `--init` explicitly creates Unassessed records and refuses an existing progress file. `--set` replaces one complete screen record; preserve existing checklist IDs, evidence and state references. Read the revision with `--json` first. Do not retry a stale revision by blindly substituting a new one: reload and reconcile changes. `updatedAt` is stamped on successful record writes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ketatlas",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Interactive HTML maps for screens, workflows, and user journeys.",
   "type": "module",
   "license": "MIT",

package/src/index.js

@@ -379,6 +379,7 @@ export function createAtlas(container, input, options = {}) {
       return;
     }
     previewNode = n;
+    progressUI.preview(n.screenId, n.flowId, n.id);
     $("dialog-screen-id").textContent = n.screenId;
     $("dialog-title").textContent = n.title;
     $("dialog-open").href = n.url;

package/src/progress-ui.js

@@ -20,7 +20,8 @@ export function mountProgress(root, config, initial, options, selectScreen) {
     editing,
     draft,
     baseline,
-    saving = false;
+    saving = false,
+    preview;
   const $ = (id) => root.getElementById(id);
   const container = document.createElement("div");
   container.innerHTML = `
@@ -70,8 +71,29 @@ export function mountProgress(root, config, initial, options, selectScreen) {
           : "pending";
     }
   }
+  function paintPreview() {
+    if (!preview) return;
+    const r = record(preview.screenId);
+    const checks = (r.checks || []).filter((c) =>
+      c.nodes?.some((n) => n.flowId === preview.flowId && n.nodeId === preview.nodeId),
+    );
+    const prs = (r.evidence || [])
+      .filter((ev) => ev.kind === "pr")
+      .map((ev) => {
+        const url = safeURL(ev.url, options.baseURL || document.baseURI);
+        const parts = new URL(url, document.baseURI).pathname.match(/\/([^/]+)\/pull\/(\d+)\/?$/);
+        const title = parts ? `${parts[1]}#${parts[2]}` : ev.title;
+        return `<a href="${e(url)}" target="_blank" rel="noopener noreferrer" title="${e(ev.title)}">${e(title)}${ev.state ? ` <span>· ${e(ev.state)}</span>` : ""} ↗</a>`;
+      });
+    $("dialog-progress").innerHTML =
+      `<div class="preview-status"><span>Screen status</span>${badge(r)}${checks.length ? `<span>State checks: ${checks.filter((c) => c.done).length}/${checks.length}</span>` : ""}</div>${r.blocker?.trim() ? `<p class="preview-blocker">${e(r.blocker)}</p>` : ""}<div class="preview-prs" aria-label="Screen pull requests">${prs.length ? prs.join("") : "<span>No linked PRs</span>"}</div>`;
+  }
+  $("dialog-progress-details").onclick = () => {
+    if (preview) edit(preview.screenId);
+  };
   function paint() {
     paintSidebar();
+    paintPreview();
     for (const el of root.querySelectorAll("[data-progress-screen]"))
       el.innerHTML = badge(record(el.dataset.progressScreen));
     const summary = summarizeProgress(data, config.screens);
@@ -274,7 +296,7 @@ export function mountProgress(root, config, initial, options, selectScreen) {
       $("progress-error").textContent = err.message;
       $("progress-reload-latest").hidden = !options.reloadProgress;
     } finally {
-      saving = false;
+      ((saving = false), preview);
       $("progress-save").disabled = false;
     }
   };
@@ -283,6 +305,10 @@ export function mountProgress(root, config, initial, options, selectScreen) {
     edit,
     paint,
     paintSidebar,
+    preview(screenId, flowId, nodeId) {
+      preview = { screenId, flowId, nodeId };
+      paintPreview();
+    },
     open() {
       paint();
       $("progress-screens").showModal();

package/src/template.js

@@ -30,7 +30,7 @@ export function template(config) {
         <div class="map-minimap"><span>Current flow</span><svg id="minimap" viewBox="0 0 168 114" role="img" aria-label="Current viewport position"></svg><button id="minimap-fit">Fit entire flow</button></div>
       </main>
     </div>
-    <dialog id="screen-dialog" class="screen-dialog" aria-labelledby="dialog-title"><header><div><small id="dialog-screen-id"></small><h2 id="dialog-title"></h2></div><button id="close-screen" class="icon-button" aria-label="Close preview"></button></header><div id="dialog-preview"></div><footer><p>Interactive preview</p><a id="dialog-open" data-ui="action" data-variant="secondary" target="_blank" rel="noopener noreferrer">Open in new tab</a></footer></dialog>
+    <dialog id="screen-dialog" class="screen-dialog" aria-labelledby="dialog-title"><header><div><small id="dialog-screen-id"></small><h2 id="dialog-title"></h2></div><button id="close-screen" class="icon-button" aria-label="Close preview"></button></header><div id="dialog-preview"></div><footer><div id="dialog-progress" class="preview-progress"></div><div class="preview-actions"><button id="dialog-progress-details" data-ui="action" data-variant="secondary">Progress details</button><a id="dialog-open" data-ui="action" data-variant="secondary" target="_blank" rel="noopener noreferrer">Open in new tab</a></div></footer></dialog>
     <dialog id="help-dialog" class="help-dialog" aria-labelledby="help-title"><h2 id="help-title">Explore the whole journey</h2><ul>
       <li>Drag the canvas or a screen card to move around.</li><li>Use + / −, Ctrl/⌘ + scroll, or pinch to zoom.</li><li>Choose a workflow in the sidebar. Fit the flow to see every branch.</li><li>Click a node to follow its outgoing steps. Double-click a screen to interact.</li><li>Use arrow keys to pan, F to fit, 0 to return to the start, and Escape to close.</li>
     </ul><p>Arrows describe the authored flow. Embedded screens keep their own behavior.</p><button id="close-help" data-ui="action" data-variant="primary">Got it</button></dialog>

package/styles/ketatlas.css

@@ -1357,3 +1357,52 @@ a svg {
     font-size: var(--kv-text-2xs);
   }
 }
+
+/* Keep delivery context visible while scrolling a full-size screen preview. */
+.screen-dialog footer {
+  position: sticky;
+  bottom: 0;
+  z-index: 1;
+  background: var(--kv-panel-bg);
+  flex-wrap: wrap;
+  max-height: 40dvh;
+  overflow: auto;
+}
+.preview-progress {
+  flex: 1;
+  min-width: min(240px, 100%);
+  font-size: var(--kv-text-xs);
+}
+.preview-status,
+.preview-prs,
+.preview-actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--kv-space-2);
+}
+.preview-status {
+  color: var(--kv-text-muted);
+}
+.preview-prs {
+  margin-top: var(--kv-space-2);
+  color: var(--kv-text-muted);
+}
+.preview-prs a {
+  color: var(--kv-accent);
+  overflow-wrap: anywhere;
+}
+.preview-prs a span {
+  color: var(--kv-text-muted);
+}
+.screen-dialog .preview-blocker {
+  color: var(--kv-warning);
+  margin-top: var(--kv-space-2);
+  overflow-wrap: anywhere;
+}
+.preview-actions {
+  margin-left: auto;
+}
+.preview-actions [data-ui] {
+  font-size: var(--kv-text-xs);
+}

package/templates/basic/README.md

@@ -7,7 +7,7 @@ npx ketatlas serve atlas.json
 npx ketatlas audit atlas.json --strict
 ```
 
-Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.1 and use ketatlas serve atlas.json.
+Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.2 and use ketatlas serve atlas.json.
 
 Edit the HTML files in screens/ to replace the sample product. styles/design-system.css is generated from the pinned KetJS design system; do not manually fork its tokens.
 

package/templates/process/README.md

@@ -7,7 +7,7 @@ npx ketatlas serve atlas.json
 npx ketatlas audit atlas.json --strict
 ```
 
-Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.1 and use ketatlas serve atlas.json.
+Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.2 and use ketatlas serve atlas.json.
 
 This template models a process without HTML screens. Add a screen registry and screen nodes when needed.
 

package/templates/web/README.md

@@ -7,7 +7,7 @@ npx ketatlas serve atlas.json
 npx ketatlas audit atlas.json --strict
 ```
 
-Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.1 and use ketatlas serve atlas.json.
+Edit `atlas.json` to change nodes, edges, and screen URLs. Screen URLs are relative to that file. Refresh the browser after editing. No wrapper HTML, package manifest, lockfile, node_modules, or build step is needed. Alternatively, install the CLI once with npm install --global ketatlas@0.2.2 and use ketatlas serve atlas.json.
 
 Edit the HTML files in screens/ to replace the sample product. styles/design-system.css is generated from the pinned KetJS design system; do not manually fork its tokens.