@hachej/boring-feedback 0.0.0-stage → 0.2.4

package/dist/preview/page.js

@@ -0,0 +1,293 @@
+// The page side of a preview (FEEDBACK.md, "Preview"): what the browser subagent may do to the live application page, and nothing
+// else. Elements are referenced by the feedback pins (`p1`...) or by ids from `inspect` (`e1`...), always inside the application
+// root and never inside an ignored subtree. The only writes are inline CSS properties from an allowlist (no `url()`, no unknown
+// function, no `!important`) and the text of text-only elements; no attribute other than `style` is written, nothing is inserted,
+// submitted, fetched, navigated, stored or evaluated. Every change is logged and `revert` restores the original `style` attribute
+// and text nodes, so Discard (or a reload) leaves the page as it was. What the model reads goes through the privacy policy:
+// masked `app.dom@1` text, policy-kept attributes, accessible names, a few computed colors and sizes (never a value with `url(`).
+import { anchorOf, appElementResolution, elementAt, isExcluded, MASKED_NAME, pageDigest, serializeElement, serializePage, } from '../page/index.js';
+/** CSS properties a preview may set inline. Layout-breaking or resource-loading ones (`content`, `cursor`, `list-style-image`...) are not here. */
+export const PREVIEW_STYLE_PROPERTIES = Object.freeze([
+    'color', 'background', 'background-color', 'opacity', 'visibility',
+    'border', 'border-color', 'border-width', 'border-style', 'border-radius',
+    ...['top', 'right', 'bottom', 'left'].flatMap(side => [`border-${side}`, `border-${side}-color`, `border-${side}-width`, `border-${side}-style`]),
+    'outline', 'outline-color', 'outline-width', 'outline-style', 'outline-offset', 'box-shadow', 'text-shadow',
+    'font-size', 'font-weight', 'font-style', 'font-family', 'letter-spacing', 'line-height', 'text-align', 'text-decoration', 'text-transform', 'white-space',
+    'padding', 'padding-top', 'padding-right', 'padding-bottom', 'padding-left', 'margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+    'gap', 'width', 'height', 'min-width', 'max-width', 'min-height', 'max-height',
+    'display', 'flex-direction', 'flex-wrap', 'justify-content', 'align-items', 'align-self', 'order',
+]);
+/** CSS functions a value may call; anything else (`url`, `image-set`, `attr`, `var`, `expression`, `paint`...) is refused. */
+const FUNCTIONS = new Set(['rgb', 'rgba', 'hsl', 'hsla', 'hwb', 'lab', 'lch', 'oklab', 'oklch', 'color-mix', 'calc', 'min', 'max', 'clamp', 'linear-gradient', 'radial-gradient']);
+/** Never written to: their text is not page copy, or a change would touch a form value or a document. */
+const TEXT_REFUSED = new Set(['input', 'textarea', 'select', 'option', 'optgroup', 'script', 'style', 'iframe', 'object', 'embed', 'template', 'noscript', 'svg', 'math']);
+const STYLE_REFUSED = new Set(['script', 'style', 'template', 'noscript', 'head', 'meta', 'link', 'base']);
+/** Computed properties shown to the model by `inspect`. */
+const SHOWN = ['color', 'background-color', 'font-size', 'font-weight', 'display'];
+const MAX_CSS = 600, MAX_VALUE = 200, MAX_TEXT = 200, MAX_LISTED = 160;
+/** `prop: value; prop: value`, each checked. Returns the declarations or the reason for refusing. */
+export function parseDeclarations(css) {
+    if (typeof css !== 'string' || !css.trim())
+        return { ok: false, reason: 'give CSS declarations such as "background-color: #2f9e44"' };
+    if (css.length > MAX_CSS)
+        return { ok: false, reason: `at most ${MAX_CSS} characters of CSS` };
+    if (/[{}<>@\\]|\/\*/.test(css))
+        return { ok: false, reason: 'only plain declarations: no braces, at-rules, comments, escapes or markup' };
+    const declarations = [];
+    for (const part of css.split(';')) {
+        if (!part.trim())
+            continue;
+        const colon = part.indexOf(':');
+        if (colon < 0)
+            return { ok: false, reason: `"${part.trim().slice(0, 40)}" is not a declaration` };
+        const property = part.slice(0, colon).trim().toLowerCase(), value = part.slice(colon + 1).trim();
+        if (!PREVIEW_STYLE_PROPERTIES.includes(property))
+            return { ok: false, reason: `the property "${property.slice(0, 40)}" cannot be previewed` };
+        if (!value || value.length > MAX_VALUE)
+            return { ok: false, reason: `the value of ${property} must be 1 to ${MAX_VALUE} characters` };
+        if (value.includes('!'))
+            return { ok: false, reason: '!important is not allowed' };
+        if (/["'`]/.test(value) && property !== 'font-family')
+            return { ok: false, reason: 'quotes are allowed in font-family only' };
+        for (const match of value.matchAll(/([a-z-]*)\s*\(/gi)) {
+            const name = (match[1] ?? '').toLowerCase();
+            if (!FUNCTIONS.has(name))
+                return { ok: false, reason: `the CSS function "${name || '('}" is not allowed (no url(), image-set(), attr(), var() or expressions)` };
+        }
+        if (/javascript:|expression|behavior|binding/i.test(value))
+            return { ok: false, reason: 'that value is not allowed' };
+        declarations.push([property, value]);
+    }
+    return declarations.length ? { ok: true, declarations } : { ok: false, reason: 'no declaration was given' };
+}
+/** A shown value: never one that names a resource. */
+const safeValue = (value) => /url\s*\(|image-set|\(\s*["']/i.test(value) ? '(not shown)' : value.slice(0, MAX_VALUE);
+/** Builds the preview tools over the live application root. Pins are placed now, against a fresh masked snapshot. */
+export async function createPreviewPage(options) {
+    const { root, policy } = options;
+    const view = root.ownerDocument.defaultView;
+    const ids = new Map();
+    const idOf = new WeakMap();
+    let counter = 0;
+    const register = (element) => {
+        const known = idOf.get(element);
+        if (known)
+            return known;
+        const id = `e${++counter}`;
+        ids.set(id, element);
+        idOf.set(element, id);
+        return id;
+    };
+    // Pins: each anchor resolved against the masked page now; only exact and moved placements are usable.
+    const pins = [];
+    const pinned = new Map();
+    const snapshot = serializePage(root, policy);
+    const evaluated = await pageDigest(snapshot);
+    for (const [index, raw] of (options.anchors ?? []).entries()) {
+        const id = `p${index + 1}`;
+        let anchor;
+        try {
+            anchor = appElementResolution.schema.parse(raw);
+        }
+        catch {
+            pins.push({ id, fallback: 'an element of another kind', unplaced: 'this page places app.element@1 pins only' });
+            continue;
+        }
+        const base = { id, fallback: anchor.fallback, ...(anchor.signals.source ? { source: anchor.signals.source } : {}) };
+        const placement = appElementResolution.resolve(anchor, snapshot, evaluated);
+        const element = placement.kind === 'exact' || placement.kind === 'moved' ? elementAt(placement.range, root, snapshot) : undefined;
+        if (!element) {
+            pins.push({ ...base, unplaced: placement.kind === 'ambiguous' ? 'it matches more than one element now' : 'it is not on this page now' });
+            continue;
+        }
+        pins.push(base);
+        pinned.set(id, element);
+    }
+    const touched = new Map();
+    const log = [];
+    const labelOf = (element) => {
+        const captured = anchorOf(element, policy, { root });
+        if (captured.kind !== 'captured')
+            return { fallback: 'an element of the page' };
+        return { fallback: captured.anchor.fallback, ...(captured.anchor.signals.source ? { source: captured.anchor.signals.source } : {}) };
+    };
+    const touch = (element) => {
+        let record = touched.get(element);
+        if (!record) {
+            record = { element, label: labelOf(element), style: element.getAttribute('style') };
+            touched.set(element, record);
+        }
+        return record;
+    };
+    const resolve = (reference) => {
+        if (typeof reference !== 'string')
+            return { reason: 'give an element id such as p1 or e3' };
+        const element = pinned.get(reference) ?? ids.get(reference);
+        if (!element)
+            return { reason: `no element "${reference.slice(0, 20)}": use a pin (${pins.filter(pin => !pin.unplaced).map(pin => pin.id).join(', ') || 'none placed'}) or an id from inspect` };
+        if (!element.isConnected || !root.contains(element))
+            return { reason: `${reference} is no longer on the page` };
+        if (isExcluded(element))
+            return { reason: `${reference} is not part of the application` };
+        return { element };
+    };
+    const computed = (element, property) => {
+        try {
+            return view?.getComputedStyle(element).getPropertyValue(property).trim() ?? '';
+        }
+        catch {
+            return '';
+        }
+    };
+    const styleOf = (element) => element.style;
+    function setStyle(reference, css) {
+        const found = resolve(reference);
+        if ('reason' in found)
+            return { ok: false, reason: found.reason };
+        const { element } = found;
+        if (STYLE_REFUSED.has(element.localName) || !styleOf(element))
+            return { ok: false, reason: `${reference} cannot be styled` };
+        const parsed = parseDeclarations(css);
+        if (!parsed.ok)
+            return { ok: false, reason: parsed.reason };
+        const record = touch(element);
+        const style = styleOf(element);
+        const applied = [];
+        for (const [property, value] of parsed.declarations) {
+            const from = safeValue(style.getPropertyValue(property).trim() || computed(element, property));
+            const before = style.getPropertyValue(property);
+            style.setProperty(property, value);
+            if (!style.getPropertyValue(property)) {
+                if (before)
+                    style.setProperty(property, before);
+                else
+                    style.removeProperty(property);
+                return { ok: false, reason: `"${value}" is not a valid ${property}${applied.length ? ` (${applied.join(', ')} applied)` : ''}` };
+            }
+            log.push({ touched: record, property, from, to: safeValue(value) });
+            applied.push(`${property}: ${value}`);
+        }
+        return { ok: true, message: `${reference}: ${applied.join('; ')}` };
+    }
+    function setText(reference, text) {
+        const found = resolve(reference);
+        if ('reason' in found)
+            return { ok: false, reason: found.reason };
+        const { element } = found;
+        if (typeof text !== 'string' || !text.trim() || text.length > MAX_TEXT || /[<>]/.test(text))
+            return { ok: false, reason: `the text must be 1 to ${MAX_TEXT} characters, without markup` };
+        if (TEXT_REFUSED.has(element.localName) || element.closest('[contenteditable]:not([contenteditable=false])'))
+            return { ok: false, reason: `the text of ${reference} cannot be changed` };
+        if (element.children.length)
+            return { ok: false, reason: `${reference} contains other elements: change the text of the innermost element` };
+        const own = serializeElement(element, policy, { subtreeLimit: 1 }).root;
+        if (!own || own.text === '' || own.text !== (element.textContent ?? '').replace(/\s+/g, ' ').trim())
+            return { ok: false, reason: `the text of ${reference} is private on this page and cannot be changed in a preview` };
+        const record = touch(element);
+        if (!record.text)
+            record.text = Array.from(element.childNodes);
+        const from = (element.textContent ?? '').replace(/\s+/g, ' ').trim();
+        element.replaceChildren(element.ownerDocument.createTextNode(text));
+        log.push({ touched: record, text: true, from, to: text });
+        return { ok: true, message: `${reference}: text is now "${text}"` };
+    }
+    function hide(reference) {
+        const outcome = setStyle(reference, 'display: none');
+        return outcome.ok ? { ok: true, message: `${reference} is hidden` } : outcome;
+    }
+    function show(reference) {
+        const found = resolve(reference);
+        if ('reason' in found)
+            return { ok: false, reason: found.reason };
+        const hidden = [...log].reverse().find(entry => entry.touched.element === found.element && entry.property === 'display');
+        if (!hidden || hidden.to !== 'none')
+            return { ok: false, reason: `${reference} was not hidden by this preview` };
+        const original = /(?:^|;)\s*display\s*:\s*([^;]+)/i.exec(hidden.touched.style ?? '')?.[1]?.trim();
+        const style = styleOf(found.element);
+        if (original)
+            style.setProperty('display', original);
+        else
+            style.removeProperty('display');
+        log.push({ touched: hidden.touched, property: 'display', from: 'none', to: original ?? computed(found.element, 'display') });
+        return { ok: true, message: `${reference} is shown again` };
+    }
+    function inspect() {
+        const page = serializePage(root, policy);
+        const lines = [];
+        for (const pin of pins) {
+            const element = pinned.get(pin.id);
+            lines.push(element ? `${pin.id} = ${register(element)}: ${pin.fallback}` : `${pin.id}: ${pin.fallback} (not usable: ${pin.unplaced})`);
+        }
+        let listed = 0;
+        const visit = (node, live, depth) => {
+            if (listed >= MAX_LISTED)
+                return;
+            const role = node.attrs['role'];
+            const interesting = node.text || role || node.attrs['data-testid'] || node.attrs['data-feedback-id'] || node.attrs['data-source'] || depth === 0;
+            if (interesting) {
+                listed++;
+                const id = register(live);
+                const parts = [`${'  '.repeat(Math.min(depth, 8))}${id} ${node.tag}`];
+                if (role)
+                    parts.push(`role=${role}`);
+                if (node.text)
+                    parts.push(JSON.stringify(node.text.slice(0, 80)));
+                for (const key of ['data-testid', 'data-feedback-id', 'data-source'])
+                    if (node.attrs[key])
+                        parts.push(`${key}=${node.attrs[key]}`);
+                const styles = SHOWN.map(property => [property, safeValue(computed(live, property))]).filter(([, value]) => value);
+                if (styles.length)
+                    parts.push(`{${styles.map(([property, value]) => `${property}: ${value}`).join('; ')}}`);
+                lines.push(parts.join(' '));
+            }
+            // The live children in the snapshot's order: same tag, same index among same-tag siblings (as `elementAt` walks).
+            for (const child of node.children) {
+                let seen = 0, found;
+                for (const candidate of Array.from(live.children))
+                    if (candidate.localName === child.tag && seen++ === child.index) {
+                        found = candidate;
+                        break;
+                    }
+                if (found)
+                    visit(child, found, depth + 1);
+            }
+        };
+        if (page.root)
+            visit(page.root, root, 0);
+        if (page.truncated || listed >= MAX_LISTED)
+            lines.push('(outline truncated)');
+        lines.push(`Text shown as ${JSON.stringify(MASKED_NAME)} or with masked characters is private: do not guess it.`);
+        return lines.join('\n');
+    }
+    function changes() {
+        const net = new Map();
+        const order = [];
+        for (const entry of log) {
+            const key = `${[...touched.keys()].indexOf(entry.touched.element)}:${entry.text ? '#text' : entry.property}`;
+            const known = net.get(key);
+            if (known)
+                known.to = entry.to;
+            else {
+                net.set(key, { touched: entry.touched, ...(entry.property ? { property: entry.property } : {}), ...(entry.text ? { text: true } : {}), from: entry.from, to: entry.to });
+                order.push(key);
+            }
+        }
+        return order.map(key => net.get(key)).filter(item => item.from !== item.to).map(item => Object.freeze({
+            element: item.touched.label.fallback, ...(item.touched.label.source ? { source: item.touched.label.source } : {}),
+            ...(item.property ? { property: item.property } : { text: true }), from: item.from, to: item.to,
+        }));
+    }
+    function revert() {
+        for (const record of [...touched.values()].reverse()) {
+            if (record.style === null)
+                record.element.removeAttribute('style');
+            else
+                record.element.setAttribute('style', record.style);
+            if (record.text)
+                record.element.replaceChildren(...record.text);
+        }
+        touched.clear();
+        log.length = 0;
+    }
+    return Object.freeze({ pins: Object.freeze(pins.map(pin => Object.freeze(pin))), inspect, setStyle, setText, hide, show, changes, revert });
+}

package/dist/preview/session.d.ts

@@ -0,0 +1,63 @@
+import type { Api, Model, Models } from '@earendil-works/pi-ai';
+import type { PrivacyPolicy } from '../page/index.js';
+import type { PreviewChange } from '../format/index.js';
+export declare const BROWSER_PREVIEW_TOOL = "browser_preview";
+/** A pending browser task found in a conversation view: its answer id (`[assistantEntryId, callId]`) and its arguments. */
+export interface PendingBrowserTask {
+    readonly id: string;
+    readonly callId: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+}
+interface ViewLike {
+    readonly entries: readonly {
+        readonly id: number | bigint | string;
+        readonly model?: readonly unknown[] | undefined;
+    }[];
+    readonly docs?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The calls of `tool` in a conversation view that have no result yet, oldest first, while the conversation is running. The id is the
+ * binding `browserTaskId(entry, call)` of `@hachej/boring-agent/browser-task`, which the chat transport's `answer` takes.
+ */
+export declare function pendingBrowserTasks(view: ViewLike | undefined, tool?: string): readonly PendingBrowserTask[];
+export type PreviewStatus = 'starting' | 'working' | 'ready' | 'failed' | 'answering' | 'approved' | 'discarded';
+export interface PreviewSnapshot {
+    readonly status: PreviewStatus;
+    /** The subagent's last sentence. */
+    readonly summary: string;
+    readonly changes: readonly PreviewChange[];
+    /** Why the last step failed or the answer was refused. */
+    readonly error?: string;
+}
+export interface PreviewSession {
+    readonly getSnapshot: () => PreviewSnapshot;
+    readonly subscribe: (listener: () => void) => () => void;
+    /** Places the pins and runs the instructions. */
+    readonly start: () => Promise<void>;
+    /** A follow-up to the subagent ("darker"). */
+    readonly say: (text: string) => Promise<void>;
+    readonly approve: () => Promise<void>;
+    readonly discard: () => Promise<void>;
+    /** Reverts the page without answering (the page is closing, or another preview replaces this one). */
+    readonly dispose: () => void;
+}
+export type PreviewAnswerOutcome = {
+    readonly kind: 'answered';
+} | {
+    readonly kind: string;
+    readonly reason?: string;
+};
+export interface PreviewSessionOptions {
+    readonly task: PendingBrowserTask;
+    readonly root: () => Element | null;
+    readonly policy: PrivacyPolicy;
+    readonly models: Models;
+    readonly model: Model<Api>;
+    /** The anchors of the report the call names (`arguments.feedback`), read with the person's own access; none when it names none. */
+    readonly anchors?: (feedbackId: string) => Promise<readonly unknown[]>;
+    /** Sends the answer through the host's authenticated path (the chat transport's `answer` with `task.id`). */
+    readonly answer: (id: string, answer: string) => Promise<PreviewAnswerOutcome>;
+}
+export declare function createPreviewSession(options: PreviewSessionOptions): PreviewSession;
+export {};
+//# sourceMappingURL=session.d.ts.map

package/dist/preview/session.js

@@ -0,0 +1,110 @@
+import { createPreviewPage } from './page.js';
+import { createPreviewAgent } from './agent.js';
+export const BROWSER_PREVIEW_TOOL = 'browser_preview';
+/**
+ * The calls of `tool` in a conversation view that have no result yet, oldest first, while the conversation is running. The id is the
+ * binding `browserTaskId(entry, call)` of `@hachej/boring-agent/browser-task`, which the chat transport's `answer` takes.
+ */
+export function pendingBrowserTasks(view, tool = BROWSER_PREVIEW_TOOL) {
+    if (!view)
+        return [];
+    const live = view.docs?.['pi.live'];
+    if (!live?.run)
+        return [];
+    const calls = new Map();
+    for (const entry of view.entries)
+        for (const message of entry.model ?? []) {
+            const item = message;
+            if (item.role === 'assistant' && Array.isArray(item.content)) {
+                for (const part of item.content) {
+                    if (part.type === 'toolCall' && part.name === tool && typeof part.id === 'string') {
+                        calls.set(part.id, { id: JSON.stringify([Number(entry.id), part.id]), callId: part.id, arguments: part.arguments ?? {} });
+                    }
+                }
+            }
+            if (item.role === 'toolResult' && typeof item.toolCallId === 'string')
+                calls.delete(item.toolCallId);
+        }
+    return [...calls.values()];
+}
+export function createPreviewSession(options) {
+    let snapshot = Object.freeze({ status: 'starting', summary: '', changes: Object.freeze([]) });
+    const listeners = new Set();
+    const publish = (change) => {
+        const { error: _old, ...rest } = snapshot;
+        snapshot = Object.freeze({ ...rest, ...change });
+        for (const listener of [...listeners])
+            listener();
+    };
+    let page, agent;
+    const abort = new AbortController();
+    const settled = () => snapshot.status === 'approved' || snapshot.status === 'discarded';
+    const instructions = typeof options.task.arguments['instructions'] === 'string' ? options.task.arguments['instructions'] : '';
+    const feedback = typeof options.task.arguments['feedback'] === 'string' ? options.task.arguments['feedback'] : undefined;
+    const step = async (text) => {
+        if (!agent || !page || settled())
+            return;
+        publish({ status: 'working' });
+        const outcome = await agent.say(text, abort.signal);
+        if (settled())
+            return;
+        publish('error' in outcome
+            ? { status: page.changes().length ? 'ready' : 'failed', changes: page.changes(), error: outcome.error }
+            : { status: 'ready', summary: outcome.text, changes: page.changes() });
+    };
+    const send = async (answer, status) => {
+        publish({ status: 'answering' });
+        try {
+            const outcome = await options.answer(options.task.id, JSON.stringify(answer));
+            // Approved or discarded, the live page goes back to what is really saved: the approved changes travel in the answer.
+            if (outcome.kind === 'answered') {
+                page?.revert();
+                publish({ status });
+                return;
+            }
+            publish({ status: 'ready', error: ('reason' in outcome && outcome.reason) || `The answer was not accepted (${outcome.kind}).` });
+        }
+        catch (error) {
+            publish({ status: 'ready', error: error instanceof Error ? error.message : 'The answer could not be sent.' });
+        }
+    };
+    return Object.freeze({
+        getSnapshot: () => snapshot,
+        subscribe: (listener) => { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        start: async () => {
+            if (page)
+                return;
+            const root = options.root();
+            if (!root) {
+                publish({ status: 'failed', error: 'The application page is not open here.' });
+                return;
+            }
+            let anchors = [];
+            if (feedback && options.anchors) {
+                try {
+                    anchors = await options.anchors(feedback);
+                }
+                catch { /* preview without pins */ }
+            }
+            page = await createPreviewPage({ root, policy: options.policy, anchors });
+            agent = createPreviewAgent({ models: options.models, model: options.model, page, instructions: instructions || 'Preview the requested change.' });
+            await step();
+        },
+        say: async (text) => { if (text.trim() && snapshot.status !== 'working')
+            await step(text.trim()); },
+        approve: async () => { if (agent && !settled() && snapshot.status !== 'working')
+            await send(agent.approve(), 'approved'); },
+        discard: async () => {
+            if (settled())
+                return;
+            abort.abort();
+            if (agent) {
+                await send(agent.discard(), 'discarded');
+                return;
+            }
+            page?.revert();
+            await send({ kind: 'discarded' }, 'discarded');
+        },
+        dispose: () => { abort.abort(); page?.revert(); listeners.clear(); },
+    });
+}

package/dist/source/index.d.ts

@@ -0,0 +1,24 @@
+import type { Plugin } from 'esbuild';
+/** Build modes. Only `development` and `preview` may carry source locations. */
+export type FeedbackSourceMode = 'development' | 'preview' | 'production';
+export interface FeedbackSourceOptions {
+    /**
+     * Absolute project root. It must equal the build's `absWorkingDir`: esbuild names each JSX source relative to that
+     * directory, so this is what makes stamped paths project-relative. React is resolved from here too, so the page
+     * keeps one React instance.
+     */
+    readonly root: string;
+    readonly mode: FeedbackSourceMode;
+}
+/** The browser runtime module the plugin substitutes for `react/jsx-dev-runtime`. */
+export declare const FEEDBACK_SOURCE_RUNTIME = "@hachej/boring-feedback/source/jsx-dev-runtime";
+/**
+ * esbuild plugin for development and preview builds.
+ *
+ * The build must set `bundle: true`, `jsx: 'automatic'`, `jsxDev: true` and `absWorkingDir: root`. Every
+ * `react/jsx-dev-runtime` import (except the runtime's own) then resolves to the feedback runtime, which adds
+ * `data-source` to intrinsic elements. Production builds are refused: creating the plugin with `mode: 'production'`
+ * throws, so a production build that enables it fails.
+ */
+export declare function feedbackSourcePlugin(options: FeedbackSourceOptions): Plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/source/index.js

@@ -0,0 +1,59 @@
+/** The browser runtime module the plugin substitutes for `react/jsx-dev-runtime`. */
+export const FEEDBACK_SOURCE_RUNTIME = '@hachej/boring-feedback/source/jsx-dev-runtime';
+const REACT_DEV_RUNTIME = 'react/jsx-dev-runtime';
+const NAME = 'feedback-source';
+// Marks the plugin's own lookup of React's runtime so that lookup is not redirected again.
+const ORIGINAL = { feedbackSource: 'react-dev-runtime' };
+const trimEnd = (path) => path.replace(/[\\/]+$/, '');
+const isAbsolute = (path) => /^(?:\/|[A-Za-z]:[\\/])/.test(path);
+/**
+ * esbuild plugin for development and preview builds.
+ *
+ * The build must set `bundle: true`, `jsx: 'automatic'`, `jsxDev: true` and `absWorkingDir: root`. Every
+ * `react/jsx-dev-runtime` import (except the runtime's own) then resolves to the feedback runtime, which adds
+ * `data-source` to intrinsic elements. Production builds are refused: creating the plugin with `mode: 'production'`
+ * throws, so a production build that enables it fails.
+ */
+export function feedbackSourcePlugin(options) {
+    const { root, mode } = options;
+    if (mode === 'production')
+        throw new Error(`${NAME}: refusing a production build; source locations are for development and preview builds only`);
+    if (mode !== 'development' && mode !== 'preview')
+        throw new Error(`${NAME}: unknown mode ${JSON.stringify(mode)}; expected "development" or "preview"`);
+    if (typeof root !== 'string' || !isAbsolute(root))
+        throw new Error(`${NAME}: root must be an absolute project directory`);
+    return {
+        name: NAME,
+        setup(build) {
+            const initial = build.initialOptions;
+            if (initial.bundle !== true)
+                throw new Error(`${NAME}: the build must set bundle: true`);
+            if (initial.jsx !== 'automatic' || initial.jsxDev !== true)
+                throw new Error(`${NAME}: the build must set jsx: 'automatic' and jsxDev: true`);
+            if (initial.jsxImportSource !== undefined && initial.jsxImportSource !== 'react')
+                throw new Error(`${NAME}: jsxImportSource must be react`);
+            if (initial.absWorkingDir === undefined || trimEnd(initial.absWorkingDir) !== trimEnd(root)) {
+                throw new Error(`${NAME}: the build must set absWorkingDir to the project root (${root}) so source paths are project-relative`);
+            }
+            let runtime;
+            build.onResolve({ filter: /^react\/jsx-dev-runtime$/ }, async (args) => {
+                if (args.pluginData === ORIGINAL)
+                    return undefined;
+                const path = await (runtime ??= resolveRuntime(build, root, args.kind));
+                if (args.importer !== path)
+                    return { path };
+                const original = await build.resolve(REACT_DEV_RUNTIME, { kind: args.kind, resolveDir: root, pluginData: ORIGINAL });
+                if (original.errors.length)
+                    return { errors: original.errors };
+                return { path: original.path, external: original.external, namespace: original.namespace, sideEffects: original.sideEffects };
+            });
+        },
+    };
+}
+async function resolveRuntime(build, root, kind) {
+    const result = await build.resolve(FEEDBACK_SOURCE_RUNTIME, { kind, resolveDir: root });
+    if (result.errors.length || result.external || result.namespace !== 'file') {
+        throw new Error(`${NAME}: cannot bundle ${FEEDBACK_SOURCE_RUNTIME} from ${root}; install @hachej/boring-feedback in the project and do not mark it external`);
+    }
+    return result.path;
+}

package/dist/source/jsx-dev-runtime.d.ts

@@ -0,0 +1,5 @@
+import { Fragment, jsxDEV as reactJsxDEV } from 'react/jsx-dev-runtime';
+export { Fragment };
+type Parameter = Parameters<typeof reactJsxDEV>;
+export declare function jsxDEV(type: Parameter[0], props: Parameter[1], key: Parameter[2], isStatic: Parameter[3], source?: Parameter[4], self?: Parameter[5]): ReturnType<typeof reactJsxDEV>;
+//# sourceMappingURL=jsx-dev-runtime.d.ts.map

package/dist/source/jsx-dev-runtime.js

@@ -0,0 +1,29 @@
+// @hachej/boring-feedback/source/jsx-dev-runtime: browser code, bundled into development and preview pages by
+// `feedbackSourcePlugin`. It is React's JSX development runtime plus one attribute: intrinsic elements get
+// `data-source="<path>:<line>"` from the source esbuild passes. It uses no `process` or other Node API, and imports
+// nothing but React's own development runtime.
+import { Fragment, jsxDEV as reactJsxDEV } from 'react/jsx-dev-runtime';
+export { Fragment };
+/**
+ * `<path>:<line>` for a project-relative source, or `undefined` when the path is absolute, carries a drive letter or
+ * scheme, or contains `..` (the attribute is then omitted rather than leak or misname a location).
+ */
+function sourceLocation(source) {
+    const file = source?.fileName;
+    const line = source?.lineNumber;
+    if (typeof file !== 'string' || typeof line !== 'number' || !Number.isInteger(line) || line < 1)
+        return undefined;
+    const path = file.replaceAll('\\', '/');
+    if (path === '' || path.startsWith('/') || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(path) || path.split('/').includes('..'))
+        return undefined;
+    return `${path}:${line}`;
+}
+const isProps = (value) => typeof value === 'object' && value !== null;
+export function jsxDEV(type, props, key, isStatic, source, self) {
+    const location = typeof type === 'string' ? sourceLocation(source) : undefined;
+    // Never override an explicit data-source, and never mutate the caller's props object.
+    const stamped = location !== undefined && isProps(props) && !Object.hasOwn(props, 'data-source')
+        ? { ...props, 'data-source': location }
+        : props;
+    return reactJsxDEV(type, stamped, key, isStatic, source, self);
+}

package/dist/store/index.d.ts

@@ -0,0 +1,5 @@
+export { createFeedbackStore, feedbackId, FEEDBACK_PAGE_SIZE, FEEDBACK_LIST_LIMIT } from './store.js';
+export type { FeedbackProtection, FeedbackPermission, FeedbackAction, FeedbackSubject, FeedbackOperation, FeedbackStoreOptions, FeedbackStore, FeedbackDenied, FeedbackUnavailable, FeedbackMissing, FeedbackConflict, FeedbackUnknown, FeedbackRefusal, FeedbackStored, FeedbackApplied, FeedbackCreateResult, FeedbackResolveResult, FeedbackReadResult, FeedbackListItem, FeedbackListResult, FeedbackListQuery, FeedbackResolveInput, } from './store.js';
+export { feedbackMentionReader } from './mentions.js';
+export type { FeedbackMentionFile, FeedbackMentionReader } from './mentions.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/store/index.js

@@ -0,0 +1,4 @@
+// @hachej/boring-feedback/store (FEEDBACK.md, "Storage"): the server-side store over injected resource contracts, its operation
+// admission and reconciliation, and the mention reader. Imports `./format` and `@hachej/boring-files/platform` only.
+export { createFeedbackStore, feedbackId, FEEDBACK_PAGE_SIZE, FEEDBACK_LIST_LIMIT } from './store.js';
+export { feedbackMentionReader } from './mentions.js';

package/dist/store/mentions.d.ts

@@ -0,0 +1,17 @@
+import type { ResourceAccess } from '@hachej/boring-files';
+import type { FeedbackStore } from './store.js';
+/** Structurally the `MentionFile` of `@hachej/boring-agent` (`packages/agent/src/mentions.ts`), which this folder may not import. */
+export interface FeedbackMentionFile {
+    readonly size: number;
+    readonly bytes?: Uint8Array;
+}
+/** Structurally a `MentionReader`: undefined when the path is not a readable report. Never throws. */
+export type FeedbackMentionReader = (path: string) => Promise<FeedbackMentionFile | undefined>;
+/**
+ * A mention reader for `@<root><id>.md`: the same read authorization as `store.read`, on the report's subject, with access
+ * resolved per read. Mention paths are taken as resource paths, so the host mounts the root at the same workspace-relative
+ * path it gives the store; any other path is not this reader's and returns undefined (compose it in
+ * front of the host's file reader). The bytes are the canonical serialization of the stored report.
+ */
+export declare function feedbackMentionReader<Context>(store: Pick<FeedbackStore<Context>, 'root' | 'read'>, resolveAccess: () => ResourceAccess | Promise<ResourceAccess>): FeedbackMentionReader;
+//# sourceMappingURL=mentions.d.ts.map

package/dist/store/mentions.js

@@ -0,0 +1,27 @@
+import { FEEDBACK_ID, serializeFeedback } from '../format/index.js';
+/**
+ * A mention reader for `@<root><id>.md`: the same read authorization as `store.read`, on the report's subject, with access
+ * resolved per read. Mention paths are taken as resource paths, so the host mounts the root at the same workspace-relative
+ * path it gives the store; any other path is not this reader's and returns undefined (compose it in
+ * front of the host's file reader). The bytes are the canonical serialization of the stored report.
+ */
+export function feedbackMentionReader(store, resolveAccess) {
+    const prefix = store.root.path;
+    return async (path) => {
+        try {
+            if (typeof path !== 'string' || !path.startsWith(prefix) || !path.endsWith('.md'))
+                return undefined;
+            const id = path.slice(prefix.length, -'.md'.length);
+            if (!FEEDBACK_ID.test(id))
+                return undefined;
+            const read = await store.read(id, await resolveAccess());
+            if (read.kind !== 'available')
+                return undefined;
+            const bytes = serializeFeedback(read.report);
+            return { size: bytes.length, bytes };
+        }
+        catch {
+            return undefined;
+        }
+    };
+}