astro-dev-edit 0.11.0

package/src/client/element-context.ts

@@ -0,0 +1,308 @@
+import type { ClassifyResult, PeekResponse, SourceLoc } from '../shared/protocol.ts';
+import * as api from './api.ts';
+import { classifyCached } from './classify-cache.ts';
+import { narrowRules, rulesForElement, type MatchedRule } from './css-inspect.ts';
+import { pageSource } from './page-source.ts';
+
+/**
+ * "Everything we know about this element", assembled into one markdown block to
+ * paste into an AI assistant — what the hover pill's `copy ⧉` button produces.
+ *
+ * The knowledge is deliberately scattered and has to be gathered from three
+ * places, none of which can answer for the others:
+ *   - the **source loc** comes from source-map.ts's snapshot cache (Astro's dev
+ *     toolbar strips the annotations out of the live DOM, so it can't be read
+ *     from the element),
+ *   - the **CSS** comes from the browser's own CSSOM (which knows what applies
+ *     but not where it was authored), and
+ *   - the **source text** is only on disk, so it needs the /peek round-trip.
+ * Any of the three may come up empty; a section is then dropped or replaced
+ * with the reason, and the copy still happens. Never fail the whole payload
+ * because one part degraded.
+ *
+ * Split in two on purpose: `formatContext` is pure (an ElementContext in, a
+ * string out) and unit-tested, while `collectContext` is the DOM + fetch half
+ * that only the browser can run.
+ */
+
+/** Cap on the copied outerHTML. Big enough for a real component, small enough
+ *  that hovering a page wrapper doesn't paste a whole document. */
+const HTML_MAX = 4000;
+/** Cap on copied CSS rules. A heavily-styled element can match dozens, most of
+ *  them site-wide defaults it merely happens to match — `narrowRules` drops
+ *  those first, so what survives the cap is what names this element. */
+const RULES_MAX = 12;
+/** Source lines kept either side of the element's own line. /peek returns the
+ *  whole file (its own cap is ~1000 lines each way); this is the paste-sized
+ *  window cut out of it.
+ *
+ *  Deliberately tight. The payload's job is to identify *one* element, and a
+ *  wide window buries it: at ±30 a one-line `<a>` on line 30 of a 107-line file
+ *  quoted more than half the file, comment blocks and unrelated arrays
+ *  included, with the three lines that matter near the top. What the window
+ *  leaves out is named on the section heading, and the whole file is one
+ *  `/peek` away. */
+const SOURCE_CONTEXT = 5;
+/** Deepest DOM-path segments kept, counting from the element itself. */
+const PATH_MAX = 8;
+
+/** The source window actually quoted in the payload. */
+export interface SourceWindow {
+  file: string;
+  /** 1-based line number of `lines[0]`. */
+  startLine: number;
+  /** 1-based line the element sits on — marked in the quote. */
+  focusLine: number;
+  /** Lines in the whole file, so the payload can say what it left out. */
+  totalLines: number;
+  lines: string[];
+}
+
+/** Everything the overlay knows about one element, before formatting. */
+export interface ElementContext {
+  loc: SourceLoc;
+  /** The opening tag as rendered, e.g. `<h1 class="hero-title">`. */
+  openTag: string;
+  /** Short label for toasts/titles, e.g. `h1.hero-title`. */
+  label: string;
+  /** What a click would do, per the server's AST classification; null when it
+   *  couldn't be determined. Deliberately *not* rendered into the copied
+   *  markdown: it describes what this overlay can edit, not the element, and
+   *  an LLM reads it as a constraint on what it may change. */
+  verdict: string | null;
+  pageUrl: string;
+  /** Content-collection file backing the page, when it declares one. */
+  entryFile: string | null;
+  domPath: string;
+  html: string;
+  /** Characters the cap dropped from `html`; 0 when it's complete. */
+  htmlDropped: number;
+  rules: MatchedRule[];
+  /** Rules the cap dropped; 0 when all matched rules are present. */
+  rulesDropped: number;
+  source: SourceWindow | null;
+  /** Why `source` is null (a server refusal or a failed read), when it is. */
+  sourceUnavailable: string | null;
+}
+
+// --- Formatting (pure) -------------------------------------------------------
+
+/** Fence language for the source quote, by extension. */
+function fenceLang(file: string): string {
+  const ext = file.slice(file.lastIndexOf('.') + 1).toLowerCase();
+  if (ext === 'astro') return 'astro';
+  if (ext === 'md' || ext === 'mdx' || ext === 'markdown') return 'markdown';
+  if (ext === 'html') return 'html';
+  if (ext === 'ts' || ext === 'tsx') return 'ts';
+  if (ext === 'js' || ext === 'jsx') return 'js';
+  return '';
+}
+
+/** `>` gutter-marks the element's own line, so the model knows which of the
+ *  quoted lines is the subject without a marker polluting the code text. */
+function quoteSource(source: SourceWindow): string {
+  const last = source.startLine + source.lines.length - 1;
+  const width = String(last).length;
+  return source.lines
+    .map((line, i) => {
+      const no = source.startLine + i;
+      const mark = no === source.focusLine ? '>' : ' ';
+      return `${mark} ${String(no).padStart(width)} | ${line}`;
+    })
+    .join('\n');
+}
+
+function ruleBlock(rule: MatchedRule): string {
+  const body = rule.declarations
+    .split('\n')
+    .map((d) => `  ${d}`)
+    .join('\n');
+  const from = rule.sourceFile ? `/* ${rule.sourceFile} */\n` : '';
+  return `${from}${rule.selectorText} {\n${body}\n}`;
+}
+
+/** Render an ElementContext as the markdown that lands on the clipboard.
+ *  Every section is optional — an element with no classes has no CSS block, a
+ *  refused /peek has no source block. */
+export function formatContext(ctx: ElementContext): string {
+  const where = `${ctx.loc.file}:${ctx.loc.loc}`;
+  const out: string[] = [`# Element context — ${where}`, ''];
+
+  out.push(`- **Element** \`${ctx.openTag}\``);
+  out.push(`- **Source** ${where}`);
+  out.push(`- **Page** ${ctx.pageUrl}`);
+  if (ctx.entryFile) out.push(`- **Content entry** ${ctx.entryFile}`);
+  out.push(`- **DOM path** ${ctx.domPath}`, '');
+
+  out.push('## Rendered HTML', '```html', ctx.html, '```');
+  if (ctx.htmlDropped > 0) {
+    out.push(`_Truncated — ${ctx.htmlDropped} more characters of markup._`);
+  }
+  out.push('');
+
+  if (ctx.source) {
+    const { startLine, lines, totalLines, file } = ctx.source;
+    const last = startLine + lines.length - 1;
+    const range = lines.length === totalLines ? `all ${totalLines} lines` : `lines ${startLine}–${last} of ${totalLines}`;
+    out.push(`## Source — ${file} (${range}, \`>\` marks the element)`);
+    const lang = fenceLang(file);
+    out.push(`\`\`\`${lang}`, quoteSource(ctx.source), '```', '');
+  } else if (ctx.sourceUnavailable) {
+    out.push('## Source', `_Not available — ${ctx.sourceUnavailable}_`, '');
+  }
+
+  if (ctx.rules.length > 0) {
+    const shown = ctx.rules.length;
+    const total = shown + ctx.rulesDropped;
+    const count = ctx.rulesDropped > 0 ? `${shown} of ${total} rules` : `${shown} rule${shown === 1 ? '' : 's'}`;
+    out.push(`## CSS that applies (${count})`, '```css');
+    out.push(ctx.rules.map(ruleBlock).join('\n\n'));
+    out.push('```');
+    if (ctx.rulesDropped > 0) out.push(`_Truncated — ${ctx.rulesDropped} further matching rules._`);
+    out.push('');
+  } else {
+    out.push('## CSS that applies', '_No stylesheet rule matches this element directly (it may inherit from an ancestor, or its stylesheets are cross-origin)._', '');
+  }
+
+  return `${out.join('\n').trimEnd()}\n`;
+}
+
+/**
+ * Source paths repo-relative, the shape a person (or an assistant) can act on.
+ *
+ * Astro's `data-astro-source-file` annotations are absolute fsPaths — the pill
+ * only ever showed their basename, so it never mattered before, but
+ * "/Users/you/projects/site/src/pages/index.astro:12:3" is noise in a paste.
+ * `root` comes from /health; without it the path is left as-is rather than
+ * guessed at.
+ */
+export function relativize(file: string, root: string | null): string {
+  const path = file.replace(/\\/g, '/');
+  if (!root) return path;
+  const base = root.replace(/\\/g, '/').replace(/\/+$/, '') + '/';
+  return path.startsWith(base) ? path.slice(base.length) : path;
+}
+
+/** Cut the paste-sized window out of a /peek response (which is normally the
+ *  whole file). Exported for its own test — the arithmetic is 1-based and easy
+ *  to get wrong by one. */
+export function windowAround(peeked: PeekResponse, context = SOURCE_CONTEXT): SourceWindow {
+  const first = peeked.startLine;
+  const last = first + peeked.lines.length - 1;
+  const from = Math.max(first, peeked.focusLine - context);
+  const to = Math.min(last, peeked.focusLine + context);
+  return {
+    file: peeked.file,
+    startLine: from,
+    focusLine: peeked.focusLine,
+    totalLines: peeked.totalLines,
+    lines: peeked.lines.slice(from - first, to - first + 1),
+  };
+}
+
+// --- Collection (DOM + server) -----------------------------------------------
+
+/** Astro's own scoping class is machine-generated noise in a path label. */
+function authoredClass(el: Element): string | undefined {
+  return Array.from(el.classList).find((c) => !/^astro-[\w-]+$/.test(c));
+}
+
+/** `h1.hero-title` / `section#masthead` / `div` — one path segment. */
+function describe(el: Element): string {
+  const tag = el.tagName.toLowerCase();
+  if (el.id) return `${tag}#${el.id}`;
+  const cls = authoredClass(el);
+  return cls ? `${tag}.${cls}` : tag;
+}
+
+function domPathOf(el: HTMLElement): string {
+  const parts: string[] = [];
+  let cur: HTMLElement | null = el;
+  while (cur && cur !== document.documentElement) {
+    parts.unshift(describe(cur));
+    cur = cur.parentElement;
+  }
+  if (parts.length > PATH_MAX) return `… > ${parts.slice(-PATH_MAX).join(' > ')}`;
+  return parts.join(' > ');
+}
+
+/** The opening tag only, attributes included, as the browser renders it. */
+function openTagOf(el: HTMLElement): string {
+  const shallow = el.cloneNode(false) as HTMLElement;
+  const end = shallow.outerHTML.indexOf('>');
+  return end === -1 ? `<${el.tagName.toLowerCase()}>` : shallow.outerHTML.slice(0, end + 1);
+}
+
+/** outerHTML, capped. Nothing of the overlay's can appear in it: every panel,
+ *  outline and veil lives in the shadow root, whose host is a child of <body>
+ *  and never of the element being copied. */
+function renderedHtml(el: HTMLElement): { html: string; dropped: number } {
+  const full = el.outerHTML;
+  if (full.length <= HTML_MAX) return { html: full, dropped: 0 };
+  return { html: full.slice(0, HTML_MAX), dropped: full.length - HTML_MAX };
+}
+
+/** Phrase the AST classification the way the payload reads best. */
+function verdictOf(result: ClassifyResult): string {
+  const what =
+    result.kind === 'text'
+      ? 'editable text'
+      : result.kind === 'image'
+        ? 'image (src/alt)'
+        : `not editable in place (${result.kind})`;
+  return `${what} — ${result.reason}`;
+}
+
+async function sourceFor(
+  src: SourceLoc,
+  root: string | null,
+): Promise<Pick<ElementContext, 'source' | 'sourceUnavailable'>> {
+  try {
+    const peeked = await api.peek({ file: src.file, loc: src.loc });
+    // Not an error: the file is real but package-owned (an astro:assets
+    // <Image>, say), so the server explains instead of returning source.
+    if (peeked.refused) return { source: null, sourceUnavailable: peeked.refused };
+    const window = windowAround(peeked);
+    return { source: { ...window, file: relativize(window.file, root) }, sourceUnavailable: null };
+  } catch (err) {
+    return {
+      source: null,
+      sourceUnavailable: err instanceof Error ? err.message : 'the source file could not be read',
+    };
+  }
+}
+
+/** Gather everything for one element. Only the /peek read can be slow; the
+ *  classification is served from the hover cache in the normal case. `root` is
+ *  the project root from /health, used to render source paths repo-relative. */
+export async function collectContext(
+  el: HTMLElement,
+  src: SourceLoc,
+  root: string | null,
+): Promise<ElementContext> {
+  const { html, dropped } = renderedHtml(el);
+  const matched = rulesForElement(el);
+  const kept = narrowRules(el, matched, RULES_MAX);
+
+  let verdict: string | null = null;
+  try {
+    verdict = verdictOf(await classifyCached({ file: src.file, loc: src.loc, tag: el.tagName.toLowerCase() }));
+  } catch {
+    // Classification is a nicety here — the rest of the context still stands.
+  }
+
+  return {
+    loc: { file: relativize(src.file, root), loc: src.loc },
+    openTag: openTagOf(el),
+    label: describe(el),
+    verdict,
+    pageUrl: location.href,
+    entryFile: pageSource(),
+    domPath: domPathOf(el),
+    html,
+    htmlDropped: dropped,
+    rules: kept,
+    rulesDropped: matched.length - kept.length,
+    ...(await sourceFor(src, root)),
+  };
+}

package/src/client/features.ts

@@ -0,0 +1,81 @@
+import type { HealthResponse, UnsplashImportWidth } from '../shared/protocol.ts';
+import { UNSPLASH_DEFAULT_IMPORT_WIDTH, coerceImportWidth } from '../shared/unsplash.ts';
+
+/**
+ * Server-derived feature state, set at boot from `/health` (and refreshed by a
+ * Settings save) — the on/off flags, plus the one resolved value a surface
+ * needs before its own endpoint has answered.
+ *
+ * A **leaf module** on purpose: the media modal needs to know whether the
+ * Unsplash source is available, and reading that from `overlay.ts` would create
+ * an `overlay → router → image → media-modal → overlay` import cycle. Anything
+ * that only needs to *read* a flag imports this instead.
+ *
+ * Flags default to off, so a server that predates a flag (or a failed health
+ * check) degrades to the feature being absent rather than to a surface that
+ * errors when touched.
+ */
+
+interface Features {
+  /** The Unsplash photo source is enabled AND the server holds a usable key.
+   *  False means the media modal renders single-source, with no tab strip. */
+  unsplash: boolean;
+  /** The resolved `unsplash.importWidth`, where the picker's size select starts.
+   *  The one non-boolean here: it is server-derived and refreshed by the same
+   *  two calls, so a separate channel for it would be a second thing to keep in
+   *  step for no gain. */
+  unsplashImportWidth: UnsplashImportWidth;
+  /** The hover pill's class/ID chips and their CSS rules. */
+  cssInspector: boolean;
+  /** The "Open source" buttons and jump-to-file links. */
+  openInEditor: boolean;
+  /** The CMS entry drawer and the admin bar's entry button. */
+  entryEditor: boolean;
+}
+
+const features: Features = {
+  unsplash: false,
+  unsplashImportWidth: UNSPLASH_DEFAULT_IMPORT_WIDTH,
+  cssInspector: false,
+  openInEditor: false,
+  entryEditor: false,
+};
+
+/** Called once from `overlay.ts`'s boot, with the /health payload. */
+export function setFeatures(info: HealthResponse): void {
+  features.unsplash = info.unsplash === true;
+  // A server that predates the option says nothing — keep the default rather
+  // than resolving to a width it would not honour.
+  features.unsplashImportWidth =
+    coerceImportWidth(info.unsplashImportWidth) ?? UNSPLASH_DEFAULT_IMPORT_WIDTH;
+  features.cssInspector = info.cssInspector === true;
+  features.openInEditor = info.openInEditor === true;
+  features.entryEditor = info.entryEditor === true;
+}
+
+/** Re-read a single flag — used after the Settings panel stores a key, so the
+ *  Unsplash tab appears without a page reload. */
+export function updateFeature<K extends keyof Features>(key: K, value: Features[K]): void {
+  features[key] = value;
+}
+
+export function hasUnsplash(): boolean {
+  return features.unsplash;
+}
+
+/** Where the picker's size select starts — `has()` is boolean-typed, so the one
+ *  non-boolean gets its own reader. */
+export function unsplashImportWidth(): UnsplashImportWidth {
+  return features.unsplashImportWidth;
+}
+
+/** Keys of {@link Features} that are on/off. Narrowed rather than left as
+ *  `keyof Features` so `has('unsplashImportWidth')` is a type error instead of
+ *  a truthiness test on a width. */
+type FeatureFlag = {
+  [K in keyof Features]: Features[K] extends boolean ? K : never;
+}[keyof Features];
+
+export function has(key: FeatureFlag): boolean {
+  return features[key];
+}

package/src/client/focus.ts

@@ -0,0 +1,166 @@
+import { overlayActiveElement } from './shadow.ts';
+
+/**
+ * Modal focus containment — the keyboard half of what a backdrop does for the
+ * pointer.
+ *
+ * Every panel and drawer here is a `<div>` over a click-swallowing backdrop.
+ * That stops the pointer and nothing else: Tab walked straight out of the
+ * open panel into the site's navigation, the page's own links, Astro's dev
+ * toolbar and the admin bar behind it, with the panel still up. It reads as a
+ * modal and behaves as an overlay.
+ *
+ * `trapFocus` gives a shell the semantics (`role="dialog"`, `aria-modal`) and
+ * the behaviour (Tab cycles inside it; focus that lands outside is pulled
+ * back; the opener gets focus again on release).
+ *
+ * Two things make it more than a `querySelectorAll` loop:
+ *
+ * - **The composed tree, not the shadow tree.** The rich-text editor's
+ *   `contenteditable` is a light-DOM node `<slot>`-ed into the drawer (see
+ *   `shadow.ts::mountLight`), so `shell.querySelectorAll` cannot see it and a
+ *   trap built on that query would lock the user out of the body they came to
+ *   write. Slots are followed, in slot order, so Tab order matches what the eye
+ *   sees.
+ * - **Traps stack.** The media modal opens over the CMS drawer, and the
+ *   Settings drawer over the media modal. Only the innermost trap acts; the one
+ *   underneath resumes when it is released, exactly like `state.releaseTo`.
+ */
+
+const FOCUSABLE =
+  'a[href], button, input, select, textarea, [contenteditable], [tabindex]';
+
+const stack: Trap[] = [];
+
+interface Trap {
+  shell: HTMLElement;
+  opener: Element | null;
+}
+
+function focusable(el: Element): el is HTMLElement {
+  if (!el.matches(FOCUSABLE)) return false;
+  if ((el as HTMLInputElement).disabled) return false;
+  if (el.getAttribute('tabindex') === '-1') return false;
+  if (el.hasAttribute('contenteditable') && !(el as HTMLElement).isContentEditable) return false;
+  // Hidden things are not in the tab order; a zero-size box is the only
+  // reliable read of that from here (the panel itself is never display:none).
+  return (el as HTMLElement).getClientRects().length > 0;
+}
+
+/** Focusable descendants in composed order, following `<slot>`s. */
+function focusablesIn(node: Element, out: HTMLElement[] = []): HTMLElement[] {
+  for (const child of Array.from(node.children)) {
+    if (child instanceof HTMLSlotElement) {
+      for (const assigned of child.assignedElements()) {
+        if (focusable(assigned)) out.push(assigned);
+        focusablesIn(assigned, out);
+      }
+      continue;
+    }
+    if (focusable(child)) out.push(child);
+    focusablesIn(child, out);
+  }
+  return out;
+}
+
+/** Whether an event happened inside `shell`, slotted content included. */
+function inShell(shell: HTMLElement, e: Event): boolean {
+  return e.composedPath().includes(shell);
+}
+
+function top(): Trap | undefined {
+  return stack[stack.length - 1];
+}
+
+function onKeyDown(e: KeyboardEvent): void {
+  if (e.key !== 'Tab') return;
+  const trap = top();
+  if (!trap) return;
+  const items = focusablesIn(trap.shell);
+  if (items.length === 0) {
+    e.preventDefault();
+    return;
+  }
+  const first = items[0] as HTMLElement;
+  const last = items[items.length - 1] as HTMLElement;
+  const active = e.composedPath()[0];
+  const here = inShell(trap.shell, e);
+  if (!here) {
+    // Focus is already outside (a stray click on the page, say) — Tab brings
+    // it back rather than continuing the page's own order.
+    e.preventDefault();
+    first.focus();
+    return;
+  }
+  if (e.shiftKey && active === first) {
+    e.preventDefault();
+    last.focus();
+  } else if (!e.shiftKey && active === last) {
+    e.preventDefault();
+    first.focus();
+  }
+}
+
+function onFocusIn(e: FocusEvent): void {
+  const trap = top();
+  if (!trap) return;
+  if (inShell(trap.shell, e)) return;
+  // Focus reached the page behind the backdrop — from the browser's own
+  // address-bar cycle, or a script. Take it back.
+  const items = focusablesIn(trap.shell);
+  (items[0] ?? trap.shell).focus();
+}
+
+function listen(on: boolean): void {
+  const fn = on ? document.addEventListener : document.removeEventListener;
+  fn.call(document, 'keydown', onKeyDown as EventListener, true);
+  fn.call(document, 'focusin', onFocusIn as EventListener, true);
+}
+
+export interface TrapOptions {
+  /** Accessible name for the dialog. Defaults to the shell's own title text. */
+  label?: string;
+  /** Focus this instead of the first focusable when the trap opens. Pass null
+   *  to leave focus where the caller already put it. */
+  initial?: HTMLElement | null;
+}
+
+/**
+ * Make `shell` a modal dialog and hold focus inside it. Returns the release,
+ * which restores focus to whatever was focused when the trap opened.
+ */
+export function trapFocus(shell: HTMLElement, opts: TrapOptions = {}): () => void {
+  shell.setAttribute('role', 'dialog');
+  shell.setAttribute('aria-modal', 'true');
+  const label =
+    opts.label ??
+    shell.querySelector('.atx-panel-heading, .atx-drawer-title-text')?.textContent ??
+    '';
+  if (label) shell.setAttribute('aria-label', label);
+  // So focus has somewhere to land in a shell whose controls are all disabled
+  // mid-save, without putting the panel itself in the tab order.
+  if (!shell.hasAttribute('tabindex')) shell.tabIndex = -1;
+
+  // `document.activeElement` reports the host for anything inside the overlay,
+  // so the opener has to be read through the root to be restorable.
+  const trap: Trap = { shell, opener: overlayActiveElement() ?? document.activeElement };
+  stack.push(trap);
+  if (stack.length === 1) listen(true);
+
+  if (opts.initial !== null) {
+    const target = opts.initial ?? focusablesIn(shell)[0] ?? shell;
+    target.focus();
+  }
+
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const i = stack.indexOf(trap);
+    if (i >= 0) stack.splice(i, 1);
+    if (stack.length === 0) listen(false);
+    const opener = trap.opener;
+    if (opener instanceof HTMLElement && opener.isConnected) opener.focus();
+  };
+}
+