@hachej/boring-feedback 0.0.0-stage → 0.2.5

package/dist/ui/show.d.ts

@@ -0,0 +1,43 @@
+import { type AppElementRange, type PickerOverlay, type PrivacyPolicy } from '../page/index.js';
+export interface ShowCandidate {
+    /** 1-based, in the order resolution ranked them. */
+    readonly number: number;
+    /** The candidate's label from the privacy policy. */
+    readonly label: string;
+    readonly range: AppElementRange;
+}
+export type ShowOutcome = {
+    readonly kind: 'revealed';
+    readonly placement: 'exact' | 'moved' | 'chosen';
+    readonly element: Element;
+    readonly evaluated: string;
+}
+/** A person must choose: the candidates are numbered on the overlay and here. `choose` reveals one against the same snapshot. */
+ | {
+    readonly kind: 'choose';
+    readonly candidates: readonly ShowCandidate[];
+    readonly evaluated: string;
+    readonly choose: (number: number) => ShowOutcome;
+} | {
+    readonly kind: 'stale';
+    readonly reason: string;
+} | {
+    readonly kind: 'missing';
+    readonly reason: string;
+    readonly evaluated: string;
+} | {
+    readonly kind: 'unsupported';
+    readonly reason: string;
+};
+export interface ShowOptions {
+    readonly anchor: unknown;
+    readonly root: Element;
+    readonly policy: PrivacyPolicy;
+    /** Draws the revealed element or the numbered candidates. Without it Show only scrolls. */
+    readonly overlay?: PickerOverlay;
+    /** The note drawn with a revealed element. */
+    readonly note?: string;
+}
+/** Resolves an anchor against the live page now. Exact and moved placements are revealed; ambiguous ones wait for the person. */
+export declare function showAnchor(options: ShowOptions): Promise<ShowOutcome>;
+//# sourceMappingURL=show.d.ts.map

package/dist/ui/show.js

@@ -0,0 +1,72 @@
+// Show (FEEDBACK.md, "Pointing at elements" and "Activating it on an agent"): resolve a stored anchor against a FRESH snapshot of the
+// live page, reveal only `exact` or `moved`, number `ambiguous` candidates and let the person choose, and say honestly when the element
+// is missing, stale or of a kind this page cannot place (FEEDBACK-4, FEEDBACK-7). Nothing uncertain is revealed without that choice.
+import { APP_ELEMENT_KIND, appElementResolution, elementAt, pageDigest, pickerLabel, revealElement, serializePage, } from '../page/index.js';
+const STALE_RETRIES = 1;
+/** Resolves an anchor against the live page now. Exact and moved placements are revealed; ambiguous ones wait for the person. */
+export async function showAnchor(options) {
+    const { root, policy, overlay, note } = options;
+    const kind = typeof options.anchor === 'object' && options.anchor !== null ? options.anchor.kind : undefined;
+    if (kind !== APP_ELEMENT_KIND)
+        return { kind: 'unsupported', reason: `This page places ${APP_ELEMENT_KIND} anchors only${typeof kind === 'string' ? `, not ${kind}` : ''}.` };
+    let anchor;
+    try {
+        anchor = appElementResolution.schema.parse(options.anchor);
+    }
+    catch (error) {
+        return { kind: 'unsupported', reason: error instanceof Error ? error.message : 'The anchor is not valid.' };
+    }
+    for (let attempt = 0;; attempt++) {
+        const snapshot = serializePage(root, policy);
+        const evaluated = await pageDigest(snapshot);
+        const placement = appElementResolution.resolve(anchor, snapshot, evaluated);
+        switch (placement.kind) {
+            case 'exact':
+            case 'moved': {
+                const revealed = revealElement(placement.range, root, snapshot, policy);
+                if (revealed.kind === 'revealed') {
+                    overlay?.highlight(revealed.element, note ?? anchor.fallback);
+                    return { kind: 'revealed', placement: placement.kind, element: revealed.element, evaluated };
+                }
+                // The page changed between resolve and reveal: resolve again against a fresh snapshot, once.
+                if (attempt < STALE_RETRIES)
+                    continue;
+                overlay?.clear();
+                return { kind: 'stale', reason: revealed.reason };
+            }
+            case 'ambiguous':
+                return choice(anchor, placement.candidates, root, snapshot, evaluated, policy, overlay, note);
+            case 'missing':
+                overlay?.clear();
+                return { kind: 'missing', reason: `Nothing on this page matches ${anchor.fallback}.`, evaluated };
+            default:
+                overlay?.clear();
+                return { kind: 'unsupported', reason: `This page cannot place the anchor (${placement.kind}).` };
+        }
+    }
+}
+function choice(anchor, ranges, root, snapshot, evaluated, policy, overlay, note) {
+    const candidates = [];
+    const marks = [];
+    ranges.forEach((range, index) => {
+        const element = elementAt(range, root, snapshot);
+        candidates.push(Object.freeze({ number: index + 1, label: element ? pickerLabel(element, policy) : 'not on screen', range }));
+        // Numbers only: no candidate is scrolled to or singled out before the person chooses.
+        if (element)
+            marks.push({ element, label: String(index + 1), tone: 'candidate' });
+    });
+    overlay?.draw(marks);
+    const choose = (number) => {
+        const picked = candidates[number - 1];
+        if (!picked)
+            return { kind: 'stale', reason: `There is no candidate ${number}.` };
+        const revealed = revealElement(picked.range, root, snapshot, policy);
+        if (revealed.kind !== 'revealed') {
+            overlay?.clear();
+            return { kind: 'stale', reason: `${revealed.reason}; Show again.` };
+        }
+        overlay?.highlight(revealed.element, note ?? anchor.fallback);
+        return { kind: 'revealed', placement: 'chosen', element: revealed.element, evaluated };
+    };
+    return { kind: 'choose', candidates: Object.freeze(candidates), evaluated, choose };
+}

package/dist/ui/state.d.ts

@@ -0,0 +1,11 @@
+export interface ExternalState<State> {
+    readonly getSnapshot: () => State;
+    readonly subscribe: (listener: () => void) => () => void;
+}
+export interface WritableState<State> extends ExternalState<State> {
+    readonly set: (change: Partial<State>) => State;
+    /** Replaces the whole snapshot (drops optional fields `set` would keep). */
+    readonly replace: (next: State) => State;
+}
+export declare function createState<State extends object>(initial: State): WritableState<State>;
+//# sourceMappingURL=state.d.ts.map

package/dist/ui/state.js

@@ -0,0 +1,21 @@
+// A minimal external store: `subscribe` and `getSnapshot` fit React's `useSyncExternalStore` and any other view layer.
+export function createState(initial) {
+    let snapshot = Object.freeze({ ...initial });
+    const listeners = new Set();
+    return {
+        getSnapshot: () => snapshot,
+        subscribe: listener => { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        set: change => {
+            snapshot = Object.freeze({ ...snapshot, ...change });
+            for (const listener of [...listeners])
+                listener();
+            return snapshot;
+        },
+        replace: next => {
+            snapshot = Object.freeze({ ...next });
+            for (const listener of [...listeners])
+                listener();
+            return snapshot;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,100 @@
 {
   "name": "@hachej/boring-feedback",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.5",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "description": "Feedback people leave on what they see, usable without an agent and by agents through an opt-in capability.",
+  "sideEffects": false,
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE",
+    "INVARIANTS.md"
+  ],
+  "exports": {
+    "./format": {
+      "types": "./dist/format/index.d.ts",
+      "import": "./dist/format/index.js"
+    },
+    "./store": {
+      "types": "./dist/store/index.d.ts",
+      "import": "./dist/store/index.js"
+    },
+    "./agent": {
+      "types": "./dist/agent/index.d.ts",
+      "import": "./dist/agent/index.js"
+    },
+    "./page": {
+      "types": "./dist/page/index.d.ts",
+      "import": "./dist/page/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui/index.d.ts",
+      "import": "./dist/ui/index.js"
+    },
+    "./preview": {
+      "types": "./dist/preview/index.d.ts",
+      "import": "./dist/preview/index.js"
+    },
+    "./tickets": {
+      "types": "./dist/tickets/index.d.ts",
+      "import": "./dist/tickets/index.js"
+    },
+    "./source": {
+      "types": "./dist/source/index.d.ts",
+      "import": "./dist/source/index.js"
+    },
+    "./source/jsx-dev-runtime": {
+      "types": "./dist/source/jsx-dev-runtime.d.ts",
+      "import": "./dist/source/jsx-dev-runtime.js"
+    }
+  },
+  "peerDependencies": {
+    "@hachej/boring-ui-kit": "^0.2.5",
+    "@hachej/boring-files": "^0.2.5",
+    "@hachej/boring-agent": "^0.2.5",
+    "@earendil-works/pi-durable": "~1.1.0",
+    "@earendil-works/pi-ai": "~1.1.0",
+    "@earendil-works/chord": "~1.1.0",
+    "react": "^19.0.0",
+    "esbuild": "^0.28.2"
+  },
+  "peerDependenciesMeta": {
+    "@hachej/boring-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-durable": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/chord": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "esbuild": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hachej/boring-ui.git",
+    "directory": "packages/feedback"
+  },
+  "homepage": "https://github.com/hachej/boring-ui#readme",
+  "bugs": {
+    "url": "https://github.com/hachej/boring-ui/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}