mockpit 1.2.0 → 1.3.0

package/dist/server/decisions.d.ts

@@ -0,0 +1,23 @@
+import { type SlotInfo } from "./fills.ts";
+import { type KnobValue, type Mock, type Post, type Reply } from "./types.ts";
+export interface SlotDecision {
+    fill: string;
+    label?: string;
+    from?: string;
+    slots?: Record<string, SlotDecision>;
+}
+export interface StateDecision {
+    variant: string;
+    slots: Record<string, SlotDecision>;
+}
+export interface Decisions {
+    states: Record<string, StateDecision>;
+    knobs: Record<string, KnobValue>;
+}
+export declare function replyValues(reply: Pick<Reply, "answers" | "tuned">, mock: Pick<Mock, "asks">): Record<string, KnobValue>;
+export declare function settledValues(replies: Pick<Reply, "answers" | "tuned">[], mock: Pick<Mock, "asks" | "knobs">, posts: (Pick<Post, "knobs"> & {
+    surfaces?: Post["surfaces"];
+})[]): Record<string, KnobValue>;
+export declare function chosenFills(slots: SlotInfo[], values: Record<string, KnobValue>): Record<string, string>;
+export declare function postForState(posts: Post[], state: string | null): Post | undefined;
+export declare function decisionsFor(mock: Mock, posts: Post[], reply: Pick<Reply, "answers" | "tuned" | "mix">): Decisions | null;

package/dist/server/decisions.js

@@ -0,0 +1,99 @@
+// What a reply decided, as the screen is built: per state, the look and each
+// slot's chosen fill, with the slots inside a fill listed under it only when
+// that fill was chosen; plus every other knob value the reply set. The agent
+// reads "entry → skeleton → rows → shimmer" instead of reassembling it from
+// option ids, and `export` composes the same choice into one screen.
+// Runtime-agnostic (no node imports).
+import { slotsInSurfaces } from "./fills.js";
+import { checkKnobValue, knobFor } from "./knobs.js";
+import { inUseVersion, postAtVersion, } from "./types.js";
+// The knob values a reply carries: each chosen option's `set`, then tuning,
+// which wins, as in the viewer's resolveKnobs.
+export function replyValues(reply, mock) {
+    const out = {};
+    for (const ask of mock.asks) {
+        const answer = reply.answers[ask.id];
+        const ids = answer === undefined ? [] : Array.isArray(answer) ? answer : [answer];
+        for (const id of ids)
+            Object.assign(out, ask.options.find((o) => o.id === id)?.set ?? {});
+    }
+    return { ...out, ...reply.tuned };
+}
+// Every value the user has sent, oldest reply first so a later answer or tune
+// replaces an earlier one. Values the knobs declared now can't hold drop out:
+// the agent may have renamed or narrowed a knob since.
+export function settledValues(replies, mock, posts) {
+    const all = {};
+    for (const r of replies)
+        Object.assign(all, replyValues(r, mock));
+    const out = {};
+    for (const [path, value] of Object.entries(all)) {
+        const config = knobFor(path, mock, posts);
+        const checked = config === undefined ? null : checkKnobValue(path, config, value);
+        if (checked?.ok)
+            out[path] = checked.value;
+    }
+    return out;
+}
+// The fill each slot shows under these values: a value naming one of its
+// fills, else its default.
+export function chosenFills(slots, values) {
+    const out = {};
+    for (const s of slots) {
+        const v = values[s.part];
+        out[s.part] = typeof v === "string" && s.fills.some((f) => f.name === v) ? v : s.default;
+    }
+    return out;
+}
+// The post a state is decided by: the accepted look at its version in use,
+// else the open one.
+export function postForState(posts, state) {
+    const inState = posts.filter((p) => p.state === state);
+    const post = inState.find((p) => p.status === "accepted") ??
+        inState.find((p) => p.status === "open") ??
+        inState[0];
+    return post && (postAtVersion(post, inUseVersion(post)) ?? post);
+}
+function tree(slots, chosen, parent, mix) {
+    const out = {};
+    for (const s of slots) {
+        const same = parent
+            ? s.parent?.part === parent.part && s.parent.fill === parent.fill
+            : s.parent === null;
+        if (!same)
+            continue;
+        const fill = chosen[s.part];
+        const label = s.fills.find((f) => f.name === fill)?.label;
+        const inner = tree(slots, chosen, { part: s.part, fill }, mix);
+        out[s.part] = {
+            fill,
+            ...(label ? { label } : {}),
+            ...(mix[s.part] ? { from: mix[s.part] } : {}),
+            ...(Object.keys(inner).length ? { slots: inner } : {}),
+        };
+    }
+    return out;
+}
+// Null when the mock has no slots and the reply set no knobs: then the
+// answered asks already say everything.
+export function decisionsFor(mock, posts, reply) {
+    const values = replyValues(reply, mock);
+    const states = {};
+    const slotPaths = new Set();
+    for (const state of mock.states.length ? mock.states : [null]) {
+        const post = postForState(posts, state);
+        if (!post)
+            continue;
+        const slots = slotsInSurfaces(post.surfaces);
+        for (const s of slots)
+            slotPaths.add(s.part);
+        states[state ?? ""] = {
+            variant: post.variant,
+            slots: tree(slots, chosenFills(slots, values), null, reply.mix ?? {}),
+        };
+    }
+    const knobs = Object.fromEntries(Object.entries(values).filter(([p]) => !slotPaths.has(p)));
+    if (!slotPaths.size && !Object.keys(knobs).length)
+        return null;
+    return { states, knobs };
+}

package/dist/server/designGuide.js

@@ -29,7 +29,7 @@ export function iconsLine(design) {
 }
 const TOPIC_SUMMARY = {
     knobs: "every knob shape, how values reach html",
-    asks: "the ask JSON, scopes, the Look ask, multi",
+    asks: "the ask JSON, scopes, slots (data-fill), the Look ask, multi",
     surfaces: "markdown, diff, mermaid, code, terminal, json, image; uploads",
     html: "the contract, finish rules, tokens, kits, Tailwind, icons",
     feedback: "the feedback JSON, pending, delivery, export",
@@ -228,6 +228,9 @@ page or component, by slug; a state is one moment of it in the user's words
 ("Writing"), omitted for a single-state mock; a variant is a parallel design of
 a state; versions are its history. A part is an element marked \`data-part\`.
 The user answers asks, tunes knobs, presses Send once; you get one reply.
+Name a state by what the user sees on that screen ("Home, idle", "Proposal
+shown"), never by where it is in your process ("Prototype", "v2", "Round 2"):
+the viewer lists states as the screens of the mock.
 
 ## The loop
 
@@ -241,7 +244,8 @@ mockpit publish --mock writer --state "Writing" --variant dark --html dark.html
 mockpit ask     --mock writer "Which look?" --option Quiet=quiet --option Dark=dark
 mockpit feedback                # after the user says they answered
 mockpit publish --mock writer --state "Writing" --variant dark --parts body=b.html  # v2, one part
-mockpit export  --mock writer   # the accepted html per state
+mockpit publish --mock writer --state "Writing" --variant dark --fills bar#tabs=t.html
+mockpit export  --mock writer   # the chosen html per state
 \`\`\`
 
 Server: \`$MOCKPIT_URL\` (default http://localhost:8228; \`mockpit serve\`).
@@ -254,12 +258,37 @@ feedback on. The same name in two states is the same part. \`data-part-key\`
 tells list items apart and keeps comments anchored across a rename. Never
 declare geometry; the viewer measures it.
 
-## Ask or knob
+## The design is the UI
 
-A choice is several variants plus one ask that binds them. Ask it first. A
-variant decides everything it differs on; don't re-ask it. Visual options
-carry a \`variant\` or knob \`set\`. One render plus a control: a knob,
-\`--knobs '{...}'\`.
+Publish the screen alone, laid out for the width it ships at: no captions,
+side notes, labels or rationale beside it (they shrink the design on a phone).
+Say what a variant is in \`--note "System font, thin bars; feels like a tool"\`;
+the viewer shows it on the variant and its option. Name the widths the user
+ships to once, \`--widths 390,1280\`, and the design is shown at each, side by
+side; without them the viewer picks one for the screen it is on.
+Screens the user moves between, even across mocks, are a flow: publish each
+with \`--flow Morning --step 2\` (\`--step 0\` takes it out); the viewer walks it.
+
+## Build from components
+
+A screen made of reusable pieces (a button, a card, a header, a day strip) is
+built from them: publish each piece as its own mock (\`--kind component\`), and
+the screen (\`--kind page\`) embeds it with \`<mockpit-embed slug="card">\`.
+Vary a piece in its own mock, not by copying it into every page: the user
+sees every page it is in, a decision on it reaches all of them, and Home's
+Components tab counts the screens it is in. Topic \`surfaces\` has the details.
+
+## Ask, slot or knob
+
+Answers drive the screen. A choice is several variants plus one ask that binds
+them (ask it first), or a slot: one region's alternatives in one html, sharing
+\`data-part\`, each its own \`data-fill\` (\`<nav data-part="bar" data-fill="thin">\`).
+The viewer shows the chosen fill. A fill may hold slots, asked only while it is
+chosen. Send publish's \`suggestedSlotAsks\` (\`set: {"bar": "tabs"}\`). A variant
+decides all it differs on; don't re-ask it. Visual options carry a \`variant\`
+or knob \`set\`. One render plus a control: a knob,
+\`--knobs '{...}'\`. Declare knobs for what is worth fine-tuning (size,
+spacing, colour, density) even unasked; they wait in Tune.
 
 | knob | control |
 | --- | --- |
@@ -278,16 +307,22 @@ mix, comments, reactions, decision, text}, accepted, archived}\`. In order: answ
 decide structure (a variant answer already accepted it); tuned values become
 defaults; mix names a part to take from another variant (if it conflicts with an
 answer, the answer wins); address each comment and reaction on its part; decision
-(accept, revise, drop) replaces answers when there were no asks. Each Send arrives exactly once: in a write's
+(accept, revise, drop) replaces answers when there were no asks; \`decisions\` is
+the screen as chosen, per state: variant, then each slot's fill, nested. Each Send arrives exactly once: in a write's
 \`feedback\`, \`mockpit feedback\` or a \`mockpit watch\` line.
 A \`pending\` draft means the user is still answering. Send a nudge's
-\`suggestedAsk\` with \`ask\`.
+\`suggestedAsk\` with \`ask\`. A batch with \`resolved: true\` (no reply) means
+the user closed the mock unanswered: its \`dismissed\` asks were not worth
+answering. Don't ask them again, under any id; \`ask\` skips a dismissed id.
+The viewer shows each state its own asks and only open ones; a sent answer is
+not shown again.
 
 ## HTML
 
 Send a body fragment: no doctype, html, head or body. Keep content in normal
 flow: no \`position: fixed\`, no absolute layers over a fixed height; grid-stack
-(\`grid-area: 1/1\`) to overlap. Never hardcode a color; use the tokens below so
+(\`grid-area: 1/1\`) to overlap. A web font is decoration: the page must read
+without it. Never hardcode a color; use the tokens below so
 dark and light both work. External loads only from cdnjs.cloudflare.com, esm.sh,
 cdn.jsdelivr.net, unpkg.com and Google Fonts.
 

package/dist/server/embeds.d.ts

@@ -0,0 +1,25 @@
+import type { Embed } from "./types.ts";
+export interface EmbedTag {
+    slug: string;
+    variant: string | null;
+    version: number | null;
+}
+export interface ResolvedEmbed {
+    variant: string;
+    version: number;
+    html: string;
+    attrs?: string;
+    stamp?: string;
+}
+export type EmbedResolver = (tag: EmbedTag) => Promise<ResolvedEmbed | null>;
+export declare const MAX_EMBED_DEPTH = 6;
+export declare function parseEmbedTags(html: string): EmbedTag[];
+export declare const hasEmbedTags: (html: string) => boolean;
+export interface Expanded {
+    html: string;
+    used: Embed[];
+    stamps: string[];
+    cycle: string[] | null;
+}
+export declare function expandHtml(html: string, resolve: EmbedResolver, stack: string[]): Promise<Expanded>;
+export declare function embedsKey({ used, stamps }: Pick<Expanded, "used" | "stamps">): string;

package/dist/server/embeds.js

@@ -0,0 +1,118 @@
+// Composition: `<mockpit-embed slug="…" variant="…" version="…">` tags in any
+// mock's html are expanded server-side by inlining the referenced variant
+// version's first html surface body, recursively, so a component can be built
+// from components. A tag without `version` follows the version in use when the
+// variant it resolves to is accepted, else its latest; one without `variant`
+// follows the component's accepted variant.
+// Publish records the versions it saw on the post (`Post.embeds`), so what a
+// version rendered with stays answerable.
+//
+// Runtime-agnostic (no node imports) and string-only: the result is handed to
+// renderHtmlPage, which serves it from /s/:id under the sandbox CSP header, so
+// an inlined component body is exactly as contained as the page's own markup.
+// `<mockpit-slot>`, the tag's first name, is still read: "slot" now means a
+// part with alternative fills (fills.ts).
+// Deep enough for page › section › component › control; past it a chain is
+// almost certainly a mistake and costs a render each time.
+export const MAX_EMBED_DEPTH = 6;
+const EMBED_TAG = /<mockpit-(?:embed|slot)\b([^>]*?)(?:\/>|>\s*<\/mockpit-(?:embed|slot)\s*>|>)/gi;
+const ATTR = /([a-z-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/gi;
+function attributes(raw) {
+    const out = {};
+    ATTR.lastIndex = 0;
+    let m;
+    while ((m = ATTR.exec(raw)))
+        out[m[1].toLowerCase()] = m[2] ?? m[3] ?? m[4] ?? "";
+    return out;
+}
+function tagOf(attrRaw) {
+    const attrs = attributes(attrRaw);
+    const slug = attrs.slug ?? "";
+    if (!slug)
+        return null;
+    const version = Number(attrs.version);
+    return {
+        slug,
+        variant: attrs.variant || null,
+        version: Number.isInteger(version) && version > 0 ? version : null,
+    };
+}
+export function parseEmbedTags(html) {
+    const tags = [];
+    EMBED_TAG.lastIndex = 0;
+    let m;
+    while ((m = EMBED_TAG.exec(html))) {
+        const tag = tagOf(m[1] ?? "");
+        if (tag)
+            tags.push(tag);
+    }
+    return tags;
+}
+export const hasEmbedTags = (html) => /<mockpit-(?:embed|slot)\b/i.test(html);
+const escapeAttr = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+// Replace each tag with its resolved body, expanding that body's own tags in
+// turn. `stack` is the chain of slugs being expanded (the root mock's first),
+// so a component that reaches back up renders a marked placeholder instead of
+// recursing. An unresolvable embed renders as an empty marked-up placeholder
+// rather than vanishing, so a broken reference is visible in review instead of
+// silently changing the layout.
+export async function expandHtml(html, resolve, stack) {
+    const used = [];
+    const stamps = [];
+    let cycle = null;
+    const matches = [];
+    EMBED_TAG.lastIndex = 0;
+    let m;
+    while ((m = EMBED_TAG.exec(html)))
+        matches.push({ tag: tagOf(m[1] ?? "") });
+    const bodies = [];
+    for (const { tag } of matches) {
+        if (!tag) {
+            bodies.push(null);
+            continue;
+        }
+        const label = (variant, version) => `data-mockpit-embed="${escapeAttr(tag.slug)}"${variant ? ` data-mockpit-variant="${escapeAttr(variant)}"` : ""}${version == null ? "" : ` data-mockpit-version="${version}"`}`;
+        if (stack.includes(tag.slug)) {
+            cycle ??= [...stack.slice(stack.indexOf(tag.slug)), tag.slug];
+            bodies.push(`<div ${label(tag.variant, tag.version)} data-mockpit-cycle="1"></div>`);
+            continue;
+        }
+        if (stack.length >= MAX_EMBED_DEPTH) {
+            bodies.push(`<div ${label(tag.variant, tag.version)} data-mockpit-too-deep="1"></div>`);
+            continue;
+        }
+        const resolved = await resolve(tag);
+        if (!resolved) {
+            bodies.push(`<div ${label(tag.variant, tag.version)} data-mockpit-missing="1"></div>`);
+            continue;
+        }
+        used.push({
+            slug: tag.slug,
+            variant: resolved.variant,
+            version: resolved.version,
+            ...(tag.version != null ? { pinned: true } : {}),
+        });
+        stamps.push(resolved.stamp ?? "");
+        const inner = await expandHtml(resolved.html, resolve, [...stack, tag.slug]);
+        used.push(...inner.used);
+        stamps.push(...inner.stamps);
+        cycle ??= inner.cycle;
+        bodies.push(`<div ${label(resolved.variant, resolved.version)}${resolved.attrs ?? ""}>${inner.html}</div>`);
+    }
+    let i = 0;
+    EMBED_TAG.lastIndex = 0;
+    const out = html.replace(EMBED_TAG, (raw) => bodies[i++] ?? raw);
+    return { html: out, used, stamps, cycle };
+}
+// A short, stable key for what a document's embeds resolved to: part of the
+// render cache key and of the frame URL, so a component's new version reloads
+// every page that shows it and a stale document is never served as current.
+export function embedsKey({ used, stamps }) {
+    let h = 0x811c9dc5;
+    const s = used.map((e, i) => `${e.slug}:${e.variant}@${e.version}:${stamps[i] ?? ""}`).join("|");
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(36);
+}

package/dist/server/eventLog.js

@@ -4,6 +4,7 @@
 // the agent was told was pending. Shapes and ids only, never html or comment
 // text: the store already holds the content under the same ids, and a log that
 // copied it would be a second, unbounded store. `scripts/inspect.ts` reads it.
+import { isViewerRequest } from "./viewerRequest.js";
 const MAX_ERROR = 300;
 const CLIENT = /^[\w.@/-]{1,64}$/;
 export function clientOf(header, viewer, mcp) {
@@ -112,7 +113,7 @@ export function logMiddleware(sink) {
     return async (c, next) => {
         const start = Date.now();
         await next();
-        const viewer = c.req.header("sec-fetch-site") === "same-origin";
+        const viewer = isViewerRequest(c.req.raw);
         if (!loggable(c, viewer))
             return;
         try {

package/dist/server/feedbackBatch.d.ts

@@ -1,8 +1,12 @@
+import { type Decisions } from "./decisions.ts";
 import { type AskOption, type Comment, type CommentAnchor, type Mock, OTHER_ID, type PartComment, type Post, type Reaction, type Reply, type Store } from "./types.ts";
 export interface VariantRef {
     state: string | null;
     variant: string;
 }
+export interface InUseRef extends VariantRef {
+    version: number;
+}
 export interface FeedbackComment {
     seq: number;
     text: string;
@@ -35,6 +39,7 @@ export interface FeedbackReply extends Omit<Reply, "others" | "notes" | "otherIm
     at: string;
     asks: AnsweredAsk[];
     reactions?: string[];
+    decisions?: Decisions;
 }
 export interface FeedbackBatch {
     mockId: string | null;
@@ -43,9 +48,15 @@ export interface FeedbackBatch {
     title: string | null;
     reply: FeedbackReply | null;
     comments: FeedbackComment[];
-    accepted: VariantRef[];
+    accepted: InUseRef[];
     archived: VariantRef[];
+    dropped: VariantRef[];
     handoff?: string;
+    resolved?: true;
+    dismissed?: {
+        ask: string;
+        text: string;
+    }[];
 }
 export declare function reactionLine(c: PartComment & {
     reaction: Reaction;

package/dist/server/feedbackBatch.js

@@ -2,7 +2,8 @@
 // The `feedback` verb, the watch long-poll and the write piggyback all return this,
 // so an agent reads one grouped object instead of re-deriving which mock a flat
 // comment list belongs to. Runtime-agnostic (no node imports).
-import { builtinAsk, DEFAULT_VARIANT, OTHER_ID, } from "./types.js";
+import { decisionsFor } from "./decisions.js";
+import { builtinAsk, inUseVersion, DEFAULT_VARIANT, OTHER_ID, } from "./types.js";
 const ref = (p) => ({ state: p.state, variant: p.variant });
 const REACTION_LEAD = {
     up: "👍",
@@ -74,7 +75,7 @@ export function groupFeedback(comments, mocks, posts, base = "") {
         const mock = c.mockId ? mocks.get(c.mockId) : undefined;
         const mockPosts = (c.mockId && posts.get(c.mockId)) || [];
         let batch = open.get(key);
-        if (!batch || (c.kind === "reply" && batch.reply)) {
+        if (!batch || (c.kind === "reply" && (batch.reply || batch.resolved))) {
             batch = {
                 mockId: c.mockId,
                 project: mock?.project ?? null,
@@ -84,10 +85,20 @@ export function groupFeedback(comments, mocks, posts, base = "") {
                 comments: [],
                 accepted: [],
                 archived: [],
+                dropped: [],
             };
             open.set(key, batch);
             batches.push(batch);
         }
+        if (c.kind === "reply" && c.payload?.resolved) {
+            batch.resolved = true;
+            batch.dismissed = c.payload.resolved.dismissed.map((id) => ({
+                ask: id,
+                text: (mock?.asks.find((a) => a.id === id) ?? (mock && builtinAsk(mock, mockPosts, id)))
+                    ?.text ?? "",
+            }));
+            continue;
+        }
         if (c.kind === "reply" && c.payload) {
             const { others: _others, notes: _notes, otherImages: _otherImages, noteImages: _noteImages, ...payload } = c.payload;
             const reactions = (payload.comments ?? []).filter(isReaction).map(reactionLine);
@@ -99,8 +110,14 @@ export function groupFeedback(comments, mocks, posts, base = "") {
                 asks: answered(c.payload, mock, mockPosts, base),
                 ...(reactions.length ? { reactions } : {}),
             };
-            batch.accepted = mockPosts.filter((p) => p.status === "accepted").map(ref);
+            const decisions = mock ? decisionsFor(mock, mockPosts, c.payload) : null;
+            if (decisions)
+                batch.reply.decisions = decisions;
+            batch.accepted = mockPosts
+                .filter((p) => p.status === "accepted")
+                .map((p) => ({ ...ref(p), version: inUseVersion(p) }));
             batch.archived = mockPosts.filter((p) => p.status === "archived").map(ref);
+            batch.dropped = mockPosts.filter((p) => p.status === "dropped").map(ref);
             continue;
         }
         const post = c.postId ? mockPosts.find((p) => p.id === c.postId) : undefined;

package/dist/server/fills.d.ts

@@ -0,0 +1,41 @@
+import type { Knobs, Surface } from "./types.ts";
+export interface Fill {
+    name: string;
+    label?: string;
+}
+export interface SlotInfo {
+    part: string;
+    label?: string;
+    fills: Fill[];
+    default: string;
+    parent: {
+        part: string;
+        fill: string;
+    } | null;
+}
+interface Range {
+    part: string;
+    fill: string;
+    start: number;
+    end: number;
+    tagEnd: number;
+}
+export interface FillScan {
+    slots: SlotInfo[];
+    ranges: Range[];
+}
+export declare function scanFills(html: string): FillScan;
+export declare function slotKnobs(slots: SlotInfo[]): Knobs;
+export declare function slotCss(slots: SlotInfo[]): string;
+export declare function composeFills(html: string, chosen: Record<string, string>): string;
+export declare function slotsInSurfaces(surfaces: Surface[]): SlotInfo[];
+export type FillSplice = {
+    ok: true;
+    surfaces: Surface[];
+    applied: string[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function spliceFills(surfaces: Surface[], edits: Record<string, string>): FillSplice;
+export {};