@hachej/boring-feedback 0.0.0-stage → 0.2.4

package/dist/tickets/ticket.d.ts

@@ -0,0 +1,93 @@
+import type { ResourceAccess, ResourcePublisher, ResourceReader } from '@hachej/boring-files';
+/** One repository of a project; `role: 'app'` marks the application's own repository. */
+export interface ProjectRepo {
+    readonly repo: string;
+    readonly role?: string;
+}
+/** What the host knows about the project the assistant works for. */
+export interface ProjectInfo {
+    readonly name: string;
+    readonly repos: readonly ProjectRepo[];
+}
+/** What a sink publishes: the ticket's title, Markdown body (front matter removed), labels and id (the file name without `.md`). */
+export interface Ticket {
+    readonly id: string;
+    readonly title: string;
+    readonly body: string;
+    readonly labels: readonly string[];
+}
+export interface TicketSinkContext {
+    readonly project: ProjectInfo;
+    readonly signal?: AbortSignal;
+}
+export type TicketSinkResult = {
+    readonly url: string;
+} | {
+    readonly refused: string;
+};
+/** A platform a published ticket is mirrored to: `github`, `file`, later `linear`, `jira`... */
+export interface TicketSink {
+    readonly name: string;
+    readonly accepts: (project: ProjectInfo) => boolean;
+    readonly publish: (ticket: Ticket, context: TicketSinkContext) => Promise<TicketSinkResult>;
+}
+/**
+ * What the front matter's `ticket:` field records. `publishing` is the claim written before the sink is called: if it stays, the sink's
+ * outcome was lost and is unknown (check the platform); it is never published again.
+ */
+export type TicketOutcome = {
+    readonly sink: string;
+    readonly url: string;
+} | {
+    readonly sink?: string;
+    readonly refused: string;
+} | {
+    readonly sink: string;
+    readonly state: 'publishing';
+};
+export interface ParsedTicket {
+    readonly ticket: Ticket;
+    /** Every front matter field, values parsed as JSON when they are JSON. */
+    readonly fields: Readonly<Record<string, unknown>>;
+    readonly outcome?: TicketOutcome;
+}
+/**
+ * Read a ticket's Markdown: optional `---` front matter of `key: value` lines (values are JSON, which is also YAML flow, or plain text),
+ * then the body. The title is the `title` field, else the first `# ` heading, else the id; labels are the `labels` field's strings.
+ */
+export declare function parseTicket(id: string, markdown: string): ParsedTicket;
+/** The same Markdown with its front matter's `ticket:` field set to `outcome` (added, or a front matter created). Nothing else changes. */
+export declare function withTicketOutcome(markdown: string, outcome: TicketOutcome): string;
+export interface TicketSinkOptions {
+    /** The workspace provider (or its host wrapper): reads the ticket (latest revision) and replaces it conditionally. */
+    readonly files: ResourceReader & {
+        readonly publication: ResourcePublisher;
+        readonly providerId: string;
+    };
+    readonly project: ProjectInfo;
+    /** In order of preference: the first whose `accepts(project)` is true publishes. */
+    readonly sinks: readonly TicketSink[];
+    /** Folder of the tickets, relative to the workspace. Defaults to `tickets/`. */
+    readonly prefix?: string;
+}
+/** What `mirror` did: the outcome now recorded in the ticket, or why nothing was published. */
+export type TicketMirrorResult = {
+    readonly kind: 'recorded';
+    readonly outcome: TicketOutcome;
+} | {
+    readonly kind: 'skipped';
+    readonly reason: string;
+};
+export interface TicketSinks {
+    /** Whether `path` (workspace-relative) names a ticket. */
+    readonly isTicket: (path: string) => boolean;
+    /**
+     * Mirror the ticket at `path`, which a write just created: claim it, publish it to the first accepting sink and record the outcome.
+     * `created` is the revision the creating write left, when the host knows it: a `ticket:` field in that revision was written by the
+     * author, not by a sink, so it is replaced rather than trusted. Never throws.
+     */
+    readonly mirror: (path: string, access: ResourceAccess, created?: string) => Promise<TicketMirrorResult>;
+}
+/** The ticket sinks over the workspace: `mirror` publishes each new ticket once and writes the outcome back into its front matter. */
+export declare function createTicketSinks(options: TicketSinkOptions): TicketSinks;
+//# sourceMappingURL=ticket.d.ts.map

package/dist/tickets/ticket.js

@@ -0,0 +1,148 @@
+const FRONT = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+const FIELD = /^([A-Za-z_][A-Za-z0-9_-]*):[ \t]*(.*)$/;
+const ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+function valueOf(raw) {
+    const text = raw.trim();
+    if (!text)
+        return '';
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text.replace(/^(["'])(.*)\1$/, '$2');
+    }
+}
+function outcomeOf(value) {
+    if (!isObject(value))
+        return undefined;
+    const sink = typeof value['sink'] === 'string' ? value['sink'] : undefined;
+    if (sink && typeof value['url'] === 'string')
+        return { sink, url: value['url'] };
+    if (typeof value['refused'] === 'string')
+        return { ...(sink ? { sink } : {}), refused: value['refused'] };
+    if (sink && value['state'] === 'publishing')
+        return { sink, state: 'publishing' };
+    return undefined;
+}
+/**
+ * Read a ticket's Markdown: optional `---` front matter of `key: value` lines (values are JSON, which is also YAML flow, or plain text),
+ * then the body. The title is the `title` field, else the first `# ` heading, else the id; labels are the `labels` field's strings.
+ */
+export function parseTicket(id, markdown) {
+    const match = FRONT.exec(markdown);
+    const fields = {};
+    if (match)
+        for (const line of match[1].split(/\r?\n/)) {
+            const field = FIELD.exec(line);
+            if (field)
+                fields[field[1]] = valueOf(field[2]);
+        }
+    const body = (match ? markdown.slice(match[0].length) : markdown).trim();
+    const heading = /^#[ \t]+(.+)$/m.exec(body)?.[1]?.trim();
+    const title = typeof fields['title'] === 'string' && fields['title'].trim() ? fields['title'].trim() : heading || id;
+    const labels = Array.isArray(fields['labels']) ? [...new Set(fields['labels'].filter((label) => typeof label === 'string' && label.trim() !== '').map(label => label.trim()))] : [];
+    const outcome = outcomeOf(fields['ticket']);
+    return { ticket: { id, title, body, labels }, fields, ...(outcome ? { outcome } : {}) };
+}
+/** The same Markdown with its front matter's `ticket:` field set to `outcome` (added, or a front matter created). Nothing else changes. */
+export function withTicketOutcome(markdown, outcome) {
+    const line = `ticket: ${JSON.stringify(outcome)}`;
+    const match = FRONT.exec(markdown);
+    if (!match)
+        return `---\n${line}\n---\n${markdown}`;
+    const lines = match[1].split(/\r?\n/);
+    const at = lines.findIndex(item => /^ticket:/.test(item));
+    if (at >= 0)
+        lines[at] = line;
+    else
+        lines.push(line);
+    return `---\n${lines.join('\n')}\n---\n${markdown.slice(match[0].length)}`;
+}
+const decode = (bytes) => { try {
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+}
+catch {
+    return undefined;
+} };
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+let operations = 0;
+/** The ticket sinks over the workspace: `mirror` publishes each new ticket once and writes the outcome back into its front matter. */
+export function createTicketSinks(options) {
+    const { files, project, sinks } = options;
+    const prefix = options.prefix ?? 'tickets/';
+    if (prefix && (!prefix.endsWith('/') || prefix.startsWith('/')))
+        throw new TypeError('The ticket folder must be relative and end with a slash');
+    const pattern = new RegExp(`^${escapeRegExp(prefix)}([A-Za-z0-9][A-Za-z0-9_-]{0,63})\\.md$`);
+    const idOf = (path) => { const id = pattern.exec(path)?.[1]; return id && ID.test(id) ? id : undefined; };
+    async function latest(path, access) {
+        const read = await files.read({ target: { resource: { providerId: files.providerId, path }, view: { kind: 'published' } }, revision: { kind: 'latest' } }, access);
+        if (read.kind !== 'available')
+            return undefined;
+        const text = decode(read.snapshot.bytes);
+        return text === undefined ? undefined : { ref: read.snapshot.ref, text, mediaType: read.snapshot.mediaType };
+    }
+    /** Conditional replace of the exact revision read, with `outcome` in the front matter. Returns whether it committed. */
+    async function record(current, outcome, access) {
+        const operationId = `boring.ticket.${current.ref.resource.path}.${current.ref.revision}.${Date.now().toString(36)}.${++operations}`;
+        const result = await files.publication.publish({ operationId, atomicity: 'all-or-nothing', changes: [
+                { kind: 'replace', target: current.ref, bytes: new TextEncoder().encode(withTicketOutcome(current.text, outcome)), mediaType: current.mediaType },
+            ] }, access);
+        return result.kind === 'committed';
+    }
+    async function mirror(path, access, created) {
+        const id = idOf(path);
+        if (!id)
+            return { kind: 'skipped', reason: 'Not a ticket path' };
+        const current = await latest(path, access);
+        if (!current)
+            return { kind: 'skipped', reason: 'The ticket could not be read' };
+        const parsed = parseTicket(id, current.text);
+        // Already claimed or published: never twice. A `ticket:` field in the created revision itself was written by the author.
+        if (parsed.outcome && current.ref.revision !== created)
+            return { kind: 'skipped', reason: 'The ticket already records a sink outcome' };
+        const sink = sinks.find(candidate => { try {
+            return candidate.accepts(project);
+        }
+        catch {
+            return false;
+        } });
+        if (!sink) {
+            const outcome = { refused: `No ticket sink accepts the project "${project.name}"` };
+            return await record(current, outcome, access) ? { kind: 'recorded', outcome } : { kind: 'skipped', reason: 'The ticket changed before the refusal was recorded' };
+        }
+        // The claim: a conditional replace of the revision just read. Losing it (a person edited the ticket, another call claimed it)
+        // publishes nothing.
+        if (!await record(current, { sink: sink.name, state: 'publishing' }, access))
+            return { kind: 'skipped', reason: 'The ticket changed before it was claimed' };
+        let result;
+        try {
+            result = await sink.publish(parsed.ticket, { project, ...(access.signal ? { signal: access.signal } : {}) });
+        }
+        catch (error) {
+            result = { refused: `The ${sink.name} sink did not complete (${error instanceof Error ? error.message : 'unknown error'}); check ${sink.name} before filing again` };
+        }
+        const outcome = 'url' in result ? { sink: sink.name, url: result.url } : { sink: sink.name, refused: result.refused };
+        // The outcome replaces the claim. A person editing between the two writes only costs a re-read; three tries, then the claim stays.
+        for (let attempt = 1; attempt <= 3; attempt++) {
+            const claimed = await latest(path, access);
+            const state = claimed ? parseTicket(id, claimed.text).outcome : undefined;
+            if (!claimed || !state || !('state' in state))
+                break;
+            if (await record(claimed, outcome, access))
+                return { kind: 'recorded', outcome };
+        }
+        return { kind: 'recorded', outcome: { sink: sink.name, state: 'publishing' } };
+    }
+    return Object.freeze({
+        isTicket: (path) => idOf(path) !== undefined,
+        mirror: async (path, access, created) => {
+            try {
+                return await mirror(path, { ...access }, created);
+            }
+            catch {
+                return { kind: 'skipped', reason: 'The ticket stays as written; its front matter shows no outcome' };
+            }
+        },
+    });
+}

package/dist/ui/annotate.d.ts

@@ -0,0 +1,103 @@
+import { type FeedbackAnchor, type FeedbackDraft, type HostObserved } from '../format/index.js';
+import { type AppDomSnapshot, type PrivacyPolicy, type RouteLocation } from '../page/index.js';
+import type { SaveEndpoint, SaveResult } from './save.js';
+import { type ExternalState } from './state.js';
+/** What the host tells annotation about its page. `app` and `build` are the host's; the route comes from the policy. */
+export interface AnnotateHost {
+    readonly app: string;
+    readonly build?: string;
+    /** The application root: the only pickable and serialized part of the page. */
+    readonly root: Element;
+    readonly policy: PrivacyPolicy;
+    /** The current location; defaults to the root's window location. Only its path reaches `routeFor`. */
+    readonly location?: () => RouteLocation;
+}
+export interface AnnotationCapture {
+    readonly observed: HostObserved;
+    readonly anchors: readonly FeedbackAnchor[];
+    /** Pinned elements that could not be anchored, by pin position, with the reason. */
+    readonly refused: readonly {
+        readonly index: number;
+        readonly reason: string;
+    }[];
+    /** The one page snapshot every anchor and the digest came from. */
+    readonly snapshot: AppDomSnapshot;
+}
+/** What was observed now: one masked page snapshot and the `host` observation (subject, route template, digest and policy). */
+export declare function observePage(host: AnnotateHost): Promise<{
+    readonly observed: HostObserved;
+    readonly snapshot: AppDomSnapshot;
+}>;
+/** Anchors every pinned element against one masked page snapshot and records what was observed: subject, digest and policy. */
+export declare function captureAnnotation(host: AnnotateHost, elements: readonly Element[]): Promise<AnnotationCapture>;
+/** A general note's capture: the page observed, NO element (a question that is not about a zone). Same as `captureAnnotation(host, [])`. */
+export declare const captureGeneral: (host: AnnotateHost) => Promise<AnnotationCapture>;
+export type CopyState = {
+    readonly kind: 'idle';
+}
+/** On the clipboard. The text is kept so the sheet can show what was copied. */
+ | {
+    readonly kind: 'copied';
+    readonly text: string;
+}
+/** The clipboard refused: the sheet shows the text for a manual copy. */
+ | {
+    readonly kind: 'manual';
+    readonly text: string;
+} | {
+    readonly kind: 'refused';
+    readonly reason: string;
+};
+export type SaveState = {
+    readonly kind: 'idle';
+} | {
+    readonly kind: 'saving';
+} | SaveResult;
+export interface AnnotationSnapshot {
+    readonly said: string;
+    readonly anchors: readonly FeedbackAnchor[];
+    readonly refused: readonly {
+        readonly index: number;
+        readonly reason: string;
+    }[];
+    readonly observed: HostObserved;
+    /** Every anchor's fallback, for the sheet ("the «Save» button"). */
+    readonly targets: readonly string[];
+    readonly copy: CopyState;
+    readonly save: SaveState;
+    /** False without a host save endpoint: the sheet shows Copy only. */
+    readonly canSave: boolean;
+    /** The operation id the next Save sends; it stays the same across retries of this draft. */
+    readonly operationId: string;
+    /** True while the note is about pinned element(s). False after `clearSelection`, or when it was made without any: a general note. */
+    readonly selected: boolean;
+}
+export interface Annotation extends ExternalState<AnnotationSnapshot> {
+    readonly setSaid: (said: string) => void;
+    /**
+     * Cancels the selection: the note stops being about the pinned element(s) and becomes a general note, with NO anchor (the
+     * `feedback@1` report allows it: `anchors: []` and the text in `## Said`). What was typed is kept. Returns false, and changes
+     * nothing, when there is no selection or the draft is being saved or already saved.
+     */
+    readonly clearSelection: () => boolean;
+    readonly draft: () => FeedbackDraft;
+    /** Copy report: the never-stored report rendered through `./format`, on the clipboard. Needs no store, route or agent. */
+    readonly copy: () => Promise<CopyState>;
+    /** Save through the host endpoint, when there is one. */
+    readonly save: () => Promise<SaveState>;
+}
+export interface AnnotationOptions {
+    readonly capture: AnnotationCapture;
+    readonly save?: SaveEndpoint;
+    readonly said?: string;
+    readonly now?: () => Date;
+    /** Defaults to `copyToClipboard` from `@hachej/boring-files/platform`. */
+    readonly copyText?: (text: string) => Promise<boolean>;
+}
+/** A `feedback@1` id for a report that is only copied, never stored. */
+export declare function draftId(): string;
+/** A fresh Save operation id for one draft. */
+export declare const operationId: () => string;
+/** The headless annotate sheet. */
+export declare function createAnnotation({ capture, save, said, now, copyText }: AnnotationOptions): Annotation;
+//# sourceMappingURL=annotate.d.ts.map

package/dist/ui/annotate.js

@@ -0,0 +1,154 @@
+// Annotate state (FEEDBACK.md, "Release 1: application pages"): the pinned elements become `app.element@1` anchors and a `host`
+// observation from ONE masked page snapshot, the person types what they want to say, and the draft is copied (no store, no agent:
+// FEEDBACK-2, FEEDBACK-5) or saved through the host's endpoint with one operation id per draft across retries.
+import { copyToClipboard, randomUUID } from '@hachej/boring-files/platform';
+import { draftReport, feedbackText, FEEDBACK_LIMITS } from '../format/index.js';
+import { anchorOf, pageDigest, policyRecord, routeFor, serializePage } from '../page/index.js';
+import { createState } from './state.js';
+/** What was observed now: one masked page snapshot and the `host` observation (subject, route template, digest and policy). */
+export async function observePage(host) {
+    const { root, policy } = host;
+    const snapshot = serializePage(root, policy);
+    const digest = await pageDigest(snapshot);
+    const location = host.location?.() ?? root.ownerDocument.defaultView?.location ?? { pathname: '/' };
+    const observed = {
+        kind: 'host',
+        subject: { type: 'app-page', app: host.app, route: routeFor({ pathname: location.pathname }, policy), ...(host.build !== undefined ? { build: host.build } : {}) },
+        snapshot: snapshot.format,
+        digest: `sha256:${digest}`,
+        policy: policyRecord(policy),
+    };
+    return { observed, snapshot };
+}
+/** Anchors every pinned element against one masked page snapshot and records what was observed: subject, digest and policy. */
+export async function captureAnnotation(host, elements) {
+    const { root, policy } = host;
+    const { observed, snapshot } = await observePage(host);
+    const anchors = [];
+    const refused = [];
+    elements.slice(0, FEEDBACK_LIMITS.anchors).forEach((element, index) => {
+        const captured = anchorOf(element, policy, { root, page: snapshot });
+        if (captured.kind === 'captured')
+            anchors.push(captured.anchor);
+        else
+            refused.push({ index, reason: captured.reason });
+    });
+    if (elements.length > FEEDBACK_LIMITS.anchors)
+        refused.push({ index: FEEDBACK_LIMITS.anchors, reason: `at most ${FEEDBACK_LIMITS.anchors} elements per report` });
+    return Object.freeze({ observed, anchors: Object.freeze(anchors), refused: Object.freeze(refused), snapshot });
+}
+/** A general note's capture: the page observed, NO element (a question that is not about a zone). Same as `captureAnnotation(host, [])`. */
+export const captureGeneral = (host) => captureAnnotation(host, []);
+const BASE58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+/** A `feedback@1` id for a report that is only copied, never stored. */
+export function draftId() {
+    let out = '';
+    while (out.length < 16) {
+        const hex = randomUUID().replace(/-/g, '');
+        const random = hex.slice(0, 12) + hex.slice(13, 16) + hex.slice(17);
+        for (let at = 0; at + 2 <= random.length && out.length < 16; at += 2) {
+            const byte = Number.parseInt(random.slice(at, at + 2), 16);
+            if (byte < 232)
+                out += BASE58[byte % 58];
+        }
+    }
+    return `fb_${out}`;
+}
+/** A fresh Save operation id for one draft. */
+export const operationId = () => `draft_${randomUUID()}`;
+/** The headless annotate sheet. */
+export function createAnnotation({ capture, save, said = '', now = () => new Date(), copyText = copyToClipboard }) {
+    const state = createState({
+        said, anchors: capture.anchors, refused: capture.refused, observed: capture.observed,
+        targets: Object.freeze(capture.anchors.map(anchor => String(anchor['fallback'] ?? ''))),
+        copy: { kind: 'idle' }, save: { kind: 'idle' }, canSave: save !== undefined, operationId: operationId(),
+        selected: capture.anchors.length > 0 || capture.refused.length > 0,
+    });
+    // Whether the current operation id may have reached the store with some text: then it is kept even when the text changes, and the
+    // store answers honestly (the original report for the same draft, a conflict for a changed one). Only definite refusals free it.
+    let sent = false;
+    const draft = () => {
+        const current = state.getSnapshot();
+        return { observed: current.observed, anchors: current.anchors, said: current.said };
+    };
+    const problem = () => {
+        const current = state.getSnapshot();
+        if (!current.said.trim())
+            return 'Write what you want to say first.';
+        // A general note (no element pinned) is a note; pinned elements that all failed to anchor are not, or it would silently lose the zone.
+        if (!current.anchors.length && current.refused.length)
+            return 'No element could be anchored.';
+        return undefined;
+    };
+    return {
+        getSnapshot: state.getSnapshot,
+        subscribe: state.subscribe,
+        draft,
+        setSaid: next => {
+            const current = state.getSnapshot();
+            if (next === current.said)
+                return;
+            const settled = current.save.kind === 'saved';
+            state.set({
+                said: next, copy: { kind: 'idle' },
+                ...(settled ? {} : { save: { kind: 'idle' } }),
+                ...(!sent && !settled ? { operationId: operationId() } : {}),
+            });
+        },
+        clearSelection: () => {
+            const current = state.getSnapshot();
+            if (!current.selected || current.save.kind === 'saving' || current.save.kind === 'saved')
+                return false;
+            state.set({
+                anchors: Object.freeze([]), refused: Object.freeze([]), targets: Object.freeze([]), selected: false,
+                copy: { kind: 'idle' }, save: { kind: 'idle' },
+                // The draft changed: a fresh operation id, unless the current one may already have reached the store.
+                ...(!sent ? { operationId: operationId() } : {}),
+            });
+            return true;
+        },
+        copy: async () => {
+            const refused = problem();
+            if (refused)
+                return state.set({ copy: { kind: 'refused', reason: refused } }).copy;
+            let text;
+            try {
+                text = feedbackText(draftReport(draft(), { id: draftId(), created: now().toISOString() }));
+            }
+            catch (error) {
+                return state.set({ copy: { kind: 'refused', reason: error instanceof Error ? error.message : 'The report could not be rendered.' } }).copy;
+            }
+            let copied = false;
+            try {
+                copied = await copyText(text);
+            }
+            catch {
+                copied = false;
+            }
+            return state.set({ copy: copied ? { kind: 'copied', text } : { kind: 'manual', text } }).copy;
+        },
+        save: async () => {
+            const current = state.getSnapshot();
+            if (!save)
+                return state.set({ save: { kind: 'unavailable', reason: 'This page has no place to save feedback; use Copy.' } }).save;
+            if (current.save.kind === 'saving' || current.save.kind === 'saved')
+                return current.save;
+            const refused = problem();
+            if (refused)
+                return state.set({ save: { kind: 'invalid', reason: refused } }).save;
+            state.set({ save: { kind: 'saving' } });
+            sent = true;
+            let result;
+            try {
+                result = await save({ operationId: current.operationId, draft: draft() });
+            }
+            catch {
+                result = { kind: 'unknown', reason: 'The save did not answer; Save again to reconcile it.' };
+            }
+            // Definite refusals stored nothing: the next attempt may use a fresh id if the text changes.
+            if (result.kind === 'denied' || result.kind === 'unavailable' || result.kind === 'invalid')
+                sent = false;
+            return state.set({ save: result }).save;
+        },
+    };
+}

package/dist/ui/index.d.ts

@@ -0,0 +1,7 @@
+export { createState, type ExternalState, type WritableState } from './state.js';
+export { captureAnnotation, captureGeneral, createAnnotation, observePage, type AnnotateHost, type AnnotationCapture, type Annotation, type AnnotationOptions, type AnnotationSnapshot, type CopyState, type SaveState, } from './annotate.js';
+export { fetchSaveEndpoint, saveResultOf, parseSaveRequest, saveResponseOf, type SaveRequest, type SaveResult, type SaveEndpoint, type StoreCreateResult, } from './save.js';
+export { showAnchor, type ShowOutcome, type ShowCandidate, type ShowOptions } from './show.js';
+export { protectionNotice, ageOf, subjectLabel, listRows, reportView, type FeedbackProtection, type FeedbackRow, type ReportView, type ReportAnchorView, } from './report.js';
+export { createFeedbackSession, isPointing, pinMark, type FeedbackSession, type SessionMode, type SessionStartOptions, type FeedbackSessionOptions, type FeedbackSessionSnapshot, type FeedbackAttachment, type SessionPhase, type SessionNote, type SessionBubble, type SendState, type VoiceState, type Transcribe, type TranscribeResult, } from './session.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ui/index.js

@@ -0,0 +1,8 @@
+// @hachej/boring-feedback/ui (WP6): framework-light annotate state, Copy, draft operation ids for Save, list and report data, and Show.
+// Browser code over `./page` and `./format`; no store, agent or view-layer import. Each state exposes `subscribe`/`getSnapshot`.
+export { createState } from './state.js';
+export { captureAnnotation, captureGeneral, createAnnotation, observePage, } from './annotate.js';
+export { fetchSaveEndpoint, saveResultOf, parseSaveRequest, saveResponseOf, } from './save.js';
+export { showAnchor } from './show.js';
+export { protectionNotice, ageOf, subjectLabel, listRows, reportView, } from './report.js';
+export { createFeedbackSession, isPointing, pinMark, } from './session.js';

package/dist/ui/report.d.ts

@@ -0,0 +1,51 @@
+import { type FeedbackListItem, type FeedbackReport, type FeedbackStatus } from '../format/index.js';
+export type FeedbackProtection = 'protected' | 'unprotected';
+/** The sentence every surface shows for an unprotected store; nothing for a protected one. */
+export declare function protectionNotice(protection: FeedbackProtection): string | undefined;
+/** "just now", "5 min ago", "3 h ago", "2 days ago" relative to `now`. */
+export declare function ageOf(created: string, now?: Date): string;
+export interface FeedbackRow {
+    readonly id: string;
+    readonly title: string;
+    readonly status: FeedbackStatus;
+    /** `northwind-console /settings/:section` for host subjects; the raw key otherwise. */
+    readonly where: string;
+    readonly author: string;
+    readonly age: string;
+}
+/** `host:app-page:<app>:<route>` (parts URI-encoded by `subjectKeyOf`) as `<app> <route>`. */
+export declare function subjectLabel(key: string): string;
+export declare function listRows(items: readonly FeedbackListItem[], now?: Date): readonly FeedbackRow[];
+export interface ReportAnchorView {
+    readonly index: number;
+    readonly kind: string;
+    readonly fallback: string;
+    /** Development source location, when the anchor carries one. */
+    readonly source?: string;
+    /** Whether this page can place it (Show). */
+    readonly placeable: boolean;
+}
+export interface ReportView {
+    readonly id: string;
+    readonly title: string;
+    readonly said: string;
+    /** The report's notes, each with the fallback of the anchor it is about (none for a general note). */
+    readonly notes: readonly {
+        readonly number: number;
+        readonly text: string;
+        readonly anchor?: number;
+        readonly fallback?: string;
+        readonly voice: boolean;
+    }[];
+    readonly status: FeedbackStatus;
+    readonly author?: string;
+    readonly created: string;
+    readonly app?: string;
+    readonly route?: string;
+    readonly build?: string;
+    readonly widened: readonly string[];
+    readonly anchors: readonly ReportAnchorView[];
+    readonly resolutions: FeedbackReport['resolutions'];
+}
+export declare function reportView(report: FeedbackReport, placeable?: (kind: string) => boolean): ReportView;
+//# sourceMappingURL=report.d.ts.map

package/dist/ui/report.js

@@ -0,0 +1,58 @@
+// List and report data for `FeedbackList` and `FeedbackReport`: plain values derived from the stored reports and their list items, with the
+// store's protection stated (FEEDBACK-1). The host fetches them through its own authorized routes.
+import { isHostObserved, reportTitle } from '../format/index.js';
+/** The sentence every surface shows for an unprotected store; nothing for a protected one. */
+export function protectionNotice(protection) {
+    return protection === 'unprotected' ? 'This feedback is stored where working tools, shell and Git can change it: the store is unprotected.' : undefined;
+}
+/** "just now", "5 min ago", "3 h ago", "2 days ago" relative to `now`. */
+export function ageOf(created, now = new Date()) {
+    const seconds = Math.max(0, Math.round((now.getTime() - Date.parse(created)) / 1000));
+    if (!Number.isFinite(seconds) || seconds < 60)
+        return 'just now';
+    if (seconds < 3600)
+        return `${Math.floor(seconds / 60)} min ago`;
+    if (seconds < 86400)
+        return `${Math.floor(seconds / 3600)} h ago`;
+    const days = Math.floor(seconds / 86400);
+    return `${days} day${days === 1 ? '' : 's'} ago`;
+}
+/** `host:app-page:<app>:<route>` (parts URI-encoded by `subjectKeyOf`) as `<app> <route>`. */
+export function subjectLabel(key) {
+    const match = /^host:([^:]*):([^:]*):(.*)$/.exec(key);
+    if (!match)
+        return key;
+    const decode = (part) => { try {
+        return decodeURIComponent(part);
+    }
+    catch {
+        return part;
+    } };
+    return `${decode(match[2] ?? '')} ${decode(match[3] ?? '')}`.trim();
+}
+export function listRows(items, now = new Date()) {
+    return Object.freeze(items.map(item => Object.freeze({
+        id: item.id, title: item.title || '(no text)', status: item.status, where: subjectLabel(item.subject), author: item.author, age: ageOf(item.created, now),
+    })));
+}
+export function reportView(report, placeable = kind => kind === 'app.element@1') {
+    const observed = report.observed;
+    const host = isHostObserved(observed) ? observed : undefined;
+    const title = reportTitle(report) || '(no text)';
+    const notes = (report.notes ?? []).map((note, index) => {
+        const fallback = note.anchor !== undefined ? report.anchors[note.anchor]?.fallback : undefined;
+        return Object.freeze({ number: index + 1, text: note.text, ...(note.anchor !== undefined ? { anchor: note.anchor } : {}), ...(fallback !== undefined ? { fallback } : {}), voice: note.from === 'voice' });
+    });
+    return Object.freeze({
+        id: report.id, title, said: report.said, notes: Object.freeze(notes), status: report.status, created: report.created,
+        ...(report.author ? { author: report.author.display || report.author.principalId } : {}),
+        ...(host ? { app: host.subject.app, route: host.subject.route, ...(host.subject.build !== undefined ? { build: host.subject.build } : {}) } : {}),
+        widened: Object.freeze([...(host?.policy.widened ?? [])]),
+        anchors: Object.freeze(report.anchors.map((anchor, index) => {
+            const signals = anchor['signals'];
+            const source = typeof signals === 'object' && signals !== null && !Array.isArray(signals) ? signals['source'] : undefined;
+            return Object.freeze({ index, kind: anchor.kind, fallback: anchor.fallback, ...(typeof source === 'string' ? { source } : {}), placeable: placeable(anchor.kind) });
+        })),
+        resolutions: report.resolutions,
+    });
+}