@plannotator/ui 0.52.1 → 0.53.1

package/utils/skillReferences.ts

@@ -14,6 +14,13 @@
  * pre-feature behavior byte-for-byte.
  */
 
+import {
+  REVIEWER_SKILL_AUDIENCE,
+  skillInstructionsIncludedNote,
+  skillsReferencedHeading,
+  type SkillBlockAudience,
+} from '@plannotator/core/skill-reference-block';
+
 export type SkillRootId = 'claude' | 'codex' | 'universal';
 
 export interface SkillCatalogEntry {
@@ -331,8 +338,8 @@ export function resetSkillContentsForExport(): void {
   exportContents.clear();
 }
 
-const HUMAN_ONLY_EXPORT_NOTE =
-  'human-invocation-only: you cannot invoke this skill; the reviewer included it as context';
+const humanOnlyExportNote = (audience: SkillBlockAudience): string =>
+  `human-invocation-only: you cannot invoke this skill; the ${audience.requester} included it as context`;
 
 /**
  * The structural forms the injection block itself uses: the BEGIN/END markers
@@ -392,9 +399,9 @@ export function neutralizeSkillMarkerLines(body: string): string {
  *  and labeled so it can never read as the reviewer's own words. Body lines
  *  that imitate the markers are neutralized (see neutralizeSkillMarkerLines)
  *  so the body cannot close the block early or forge a sibling block. */
-function injectedSkillSection(name: string, body: SkillExportContent): string {
+function injectedSkillSection(name: string, body: SkillExportContent, audience: SkillBlockAudience): string {
   let out = `--- BEGIN SKILL INSTRUCTIONS: ${name} ---\n`;
-  out += `This skill cannot be invoked by a model, so its instructions are included here at the reviewer's request. Follow them when acting on this feedback.\n`;
+  out += `This skill cannot be invoked by a model, so its instructions are included here at the ${audience.requester}'s request. Follow them when acting on this ${audience.subject}.\n`;
   out += `Skill directory: ${body.dir}\n`;
   out += `Resolve any relative paths in the instructions below (e.g. references/, scripts/, assets/) against that absolute directory; your working directory is not the skill directory.\n\n`;
   out += `${neutralizeSkillMarkerLines(body.content)}\n`;
@@ -438,38 +445,68 @@ export function skillReferenceExportBlock(
 ): string {
   if (!text) return '';
   const refs = extractSkillReferences(text, exportCatalog);
-  if (refs.length === 0) return '';
+  return renderSkillReferencesBlock(refs, {
+    contentOf: (name) => exportContents.get(name),
+    injectedNames,
+    external: options?.external,
+  });
+}
+
+/** What `renderSkillReferencesBlock` needs besides the references themselves. */
+export interface SkillReferencesBlockOptions {
+  /** The SKILL.md body of a human-only skill, when it is to be injected; undefined falls back to the name + directory line. */
+  contentOf?: (name: string) => SkillExportContent | undefined;
+  /** Per-export dedupe (see skillReferenceExportBlock). */
+  injectedNames?: Set<string>;
+  /** A comment that did not come from the person in this UI: never injects (see skillReferenceExportBlock). */
+  external?: boolean;
+  /** Who is asking, about what. Default: the reviewer, about this feedback (Plannotator's export). */
+  audience?: SkillBlockAudience;
+}
 
-  const external = options?.external === true;
+/**
+ * The block itself, for references a caller already resolved: the export
+ * above per comment, and a host that composes ONE block per message (the
+ * Plannotator Inbox, with `INBOX_REPLY_SKILL_AUDIENCE`). '' when `refs` is
+ * empty. Same rules and markers as skillReferenceExportBlock.
+ */
+export function renderSkillReferencesBlock(
+  refs: readonly SkillCatalogEntry[],
+  options: SkillReferencesBlockOptions = {},
+): string {
+  if (refs.length === 0) return '';
+  const { injectedNames } = options;
+  const audience = options.audience ?? REVIEWER_SKILL_AUDIENCE;
+  const external = options.external === true;
   const toInject: Array<{ name: string; body: SkillExportContent }> = [];
-  let out = `**Skills referenced** (the reviewer is asking you to invoke these skills when acting on this feedback):\n`;
+  let out = `${skillsReferencedHeading(audience)}\n`;
   for (const ref of refs) {
     if (!ref.humanOnly) {
       out += `- \`${ref.name}\`\n`;
       continue;
     }
-    const body = exportContents.get(ref.name);
+    const body = options.contentOf?.(ref.name);
     if (body && injectedNames?.has(ref.name)) {
       // Already injected earlier in this export (necessarily by a reviewer-
       // written comment) — true regardless of who references it now.
-      out += `- \`${ref.name}\` (cannot be invoked by a model; its instructions are included earlier in this feedback)\n`;
+      out += `- \`${ref.name}\` (cannot be invoked by a model; its instructions are included earlier in this ${audience.subject})\n`;
     } else if (external) {
       // Tool-submitted comment: name + directory, never verbatim injection.
       out += ref.dir
         ? `- \`${ref.name}\` (cannot be invoked by a model; this comment came from an external tool, so its instructions are not included — SKILL.md is in ${ref.dir})\n`
-        : `- \`${ref.name}\` (${HUMAN_ONLY_EXPORT_NOTE})\n`;
+        : `- \`${ref.name}\` (${humanOnlyExportNote(audience)})\n`;
     } else if (body) {
       injectedNames?.add(ref.name);
       toInject.push({ name: ref.name, body });
-      out += `- \`${ref.name}\` (cannot be invoked by a model; its instructions are included below at the reviewer's request)\n`;
+      out += `- \`${ref.name}\` (cannot be invoked by a model; ${skillInstructionsIncludedNote(audience)})\n`;
     } else if (ref.dir) {
       out += `- \`${ref.name}\` (cannot be invoked by a model; its instructions could not be included, read SKILL.md in ${ref.dir} and follow it)\n`;
     } else {
-      out += `- \`${ref.name}\` (${HUMAN_ONLY_EXPORT_NOTE})\n`;
+      out += `- \`${ref.name}\` (${humanOnlyExportNote(audience)})\n`;
     }
   }
   for (const { name, body } of toInject) {
-    out += `\n${injectedSkillSection(name, body)}`;
+    out += `\n${injectedSkillSection(name, body, audience)}`;
   }
   return out;
 }

package/utils/storage.ts

@@ -127,6 +127,11 @@ export function getLastOpenInApp(): string {
   return getItem(OPEN_IN_APP_KEY) ?? 'reveal';
 }
 
+/** The stored "Open in app" id, or null when nothing was ever picked (no 'reveal' default). */
+export function getStoredOpenInApp(): string | null {
+  return getItem(OPEN_IN_APP_KEY);
+}
+
 export function setLastOpenInApp(id: string): void {
   setItem(OPEN_IN_APP_KEY, id);
 }

package/utils/textCut.ts

@@ -0,0 +1,41 @@
+/**
+ * Is this element's text cut (its own overflow with "…", or a line clamp)?
+ * With `partSelector`, it also counts as cut when its first descendant
+ * matching it is (a name drawn in two parts, whose first part shrinks).
+ * Rounding can hide a cut of under a pixel (a chip
+ * measured a scrollWidth of 104 in a clientWidth of 103 with its ellipsis
+ * showing, and another 98 in 98 with the text 0.06 px wider than its box),
+ * so any whole pixel counts, and where layout can be read the text's own
+ * width (a Range over its contents) is compared with the box's content width.
+ */
+export function isTextCut(el: Element | null | undefined, partSelector?: string): boolean {
+  if (typeof HTMLElement === 'undefined' || !(el instanceof HTMLElement)) return false;
+  const part = partSelector ? el.querySelector<HTMLElement>(partSelector) : null;
+  if (part && overflows(part)) return true;
+  return overflows(el);
+}
+
+function overflows(el: HTMLElement): boolean {
+  if (el.scrollWidth > el.clientWidth || el.scrollHeight > el.clientHeight + 1) return true;
+  if (el.clientWidth === 0 || typeof document.createRange !== 'function') return false;
+  const range = document.createRange();
+  range.selectNodeContents(el);
+  const text = range.getBoundingClientRect?.().width ?? 0;
+  if (!(text > 0)) return false;
+  const style = getComputedStyle(el);
+  if (style.overflowX === 'visible') return false;
+  const box = el.getBoundingClientRect().width;
+  const inner = box - num(style.paddingLeft) - num(style.paddingRight) - num(style.borderLeftWidth) - num(style.borderRightWidth);
+  // Chrome draws the ellipsis for any overflow (a chip lost 0.06 px): a hundredth of a pixel counts.
+  return text > inner + 0.01;
+}
+
+function num(value: string): number {
+  const n = Number.parseFloat(value);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** No hover on this device (a touch screen): a hover there is a first tap, so a tooltip should not open. */
+export function noHover(): boolean {
+  return typeof window !== 'undefined' && typeof window.matchMedia === 'function' && window.matchMedia('(hover: none)').matches;
+}

package/utils/updateNotice.ts

@@ -0,0 +1,120 @@
+/**
+ * Update notices in plan review, annotate and code review (design:
+ * .product/approved/plannotator-updates/ §4.5, owner's answers 1 and 3).
+ *
+ * The server says whether a newer release exists (`updateAvailable` on
+ * /api/plan and /api/diff, from the machine's once-a-day check): the browser
+ * never asks GitHub. This module parses that advert, decides whether the toast
+ * may show now (once per version, and at most once every three days across
+ * versions, remembered in a cookie that every localhost port shares), and
+ * words the toast for the host that launched the session.
+ */
+
+import { getItem, setItem } from './storage';
+import { noteServerSessionMismatch, withServerSession } from './serverSession';
+
+export type UpdateAction = 'script' | 'copy' | 'pi' | 'opencode';
+
+export interface UpdateAdvert {
+  version: string;
+  current: string;
+  releaseUrl: string;
+  action: UpdateAction;
+  /** What a person runs by hand, with the remembered install flags (`pi update --extensions` for Pi). */
+  command: string;
+  publishedAt?: string;
+}
+
+/** The toast shows at most this often, across versions. */
+export const UPDATE_TOAST_INTERVAL_MS = 3 * 24 * 60 * 60 * 1000;
+
+const TOAST_KEY = 'plannotator-update-toast';
+const VERSION = /^\d{1,9}\.\d{1,9}\.\d{1,9}$/;
+const ACTIONS: readonly UpdateAction[] = ['script', 'copy', 'pi', 'opencode'];
+
+/** The server's advert, validated (anything malformed is no advert). */
+export function parseUpdateAdvert(value: unknown): UpdateAdvert | null {
+  if (!value || typeof value !== 'object') return null;
+  const v = value as Record<string, unknown>;
+  if (typeof v.version !== 'string' || !VERSION.test(v.version)) return null;
+  if (typeof v.current !== 'string' || !VERSION.test(v.current)) return null;
+  if (typeof v.releaseUrl !== 'string' || !/^https:\/\/github\.com\//.test(v.releaseUrl)) return null;
+  if (typeof v.action !== 'string' || !ACTIONS.includes(v.action as UpdateAction)) return null;
+  if (typeof v.command !== 'string' || !v.command || v.command.length > 500) return null;
+  return {
+    version: v.version,
+    current: v.current,
+    releaseUrl: v.releaseUrl,
+    action: v.action as UpdateAction,
+    command: v.command,
+    ...(typeof v.publishedAt === 'string' && { publishedAt: v.publishedAt }),
+  };
+}
+
+function readToastRecord(): { version: string; at: number } | null {
+  const raw = getItem(TOAST_KEY);
+  if (!raw) return null;
+  const at = raw.lastIndexOf('@');
+  if (at <= 0) return null;
+  const time = Number(raw.slice(at + 1));
+  return Number.isFinite(time) ? { version: raw.slice(0, at), at: time } : null;
+}
+
+/** Whether the toast for `version` may show now (pure, for tests; `claimUpdateToast` records it). */
+export function updateToastDue(version: string, now: number, record = readToastRecord()): boolean {
+  if (!record) return true;
+  if (record.version === version) return false;
+  // A clock that moved backwards does not hold the toast back for good.
+  if (record.at > now) return true;
+  return now - record.at >= UPDATE_TOAST_INTERVAL_MS;
+}
+
+/** True the first time the toast may show for `version`; marks it shown. */
+export function claimUpdateToast(version: string, now: number): boolean {
+  if (!updateToastDue(version, now)) return false;
+  setItem(TOAST_KEY, `${version}@${now}`);
+  return true;
+}
+
+/** The toast's words and its primary action, per host. */
+export function describeUpdateToast(advert: UpdateAdvert): { title: string; description: string; primary: 'update' | 'copy' } {
+  switch (advert.action) {
+    case 'script':
+      return {
+        title: `Plannotator ${advert.version} is available`,
+        description: `You have ${advert.current}. Update from the Inbox, or turn on automatic updates in Settings.`,
+        primary: 'update',
+      };
+    case 'copy':
+      return {
+        title: `Plannotator ${advert.version} is available`,
+        description: `You have ${advert.current}. This copy was not installed by the install script: run the install command to update.`,
+        primary: 'copy',
+      };
+    case 'pi':
+      return {
+        title: `Plannotator for Pi ${advert.version} is available`,
+        description: `Run ${advert.command}, then restart Pi.`,
+        primary: 'copy',
+      };
+    case 'opencode':
+      return {
+        title: `Plannotator ${advert.version} is available`,
+        description: "Run the install script again, then restart OpenCode. It also clears OpenCode's cached plugin.",
+        primary: 'copy',
+      };
+  }
+}
+
+/** Ask the server to run the install script now (`script` only). */
+export async function requestUpdateNow(): Promise<{ ok: true; version: string } | { ok: false; error: string }> {
+  try {
+    const res = await fetch('/api/update', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(withServerSession({})) });
+    if (await noteServerSessionMismatch(res)) return { ok: false, error: 'This review was replaced by a newer Plannotator session. Reload the page.' };
+    const body = (await res.json().catch(() => ({}))) as { version?: string; error?: string };
+    if (res.ok && typeof body.version === 'string') return { ok: true, version: body.version };
+    return { ok: false, error: body.error ?? `The update could not start (HTTP ${res.status}).` };
+  } catch {
+    return { ok: false, error: 'The update could not start: the session is not reachable.' };
+  }
+}