document360-engine 0.2.9 → 0.2.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "document360-engine",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Headless documentation agent engine for document360-writer / -desktop. Emits a typed event stream; no UI.",
   "type": "module",
   "main": "./dist/index.js",

package/skills/emit-screenshot-spec/SKILL.md

@@ -2,43 +2,69 @@
 
 **Activate when** you've just emitted a `<!-- SCREENSHOT ... -->` placeholder block in an article, OR the user runs `/screenshot <id>`.
 
-**Goal:** generate a Playwright `.spec.ts` file in the configured `captureDir` that the `document360-capture` (alias `d360-capture`) CLI can execute end-to-end against the user's running product.
+**Goal:** generate a Playwright `.spec.ts` in the configured `captureDir` that the `document360-capture` (alias `d360-capture`) CLI runs against the user's live product.
 
-## Where the spec lands
+## Read the product FIRST — never guess (non-negotiable)
 
-`<captureDir>/<placeholder.id>.spec.ts` — read `captureDir` from `.d360-writer.json` (default: `user-docs/_capture`).
+Every recurring capture failure has traced back to guessing. Before you write a single line, READ the source and ground each of these in it:
+
+1. **Routes** — find the router (e.g. the app's route table) and use the EXACT path. Do not assume `/spec` vs `/spec-files`, `/tests` vs `/test`. If you can't find it, say so and ask.
+2. **Selectors** — open the component and use a stable `data-testid` you actually see. Never invent one, and never fall back to `li`, `ul.divide-y li`, or other structural CSS.
+3. **Context selection** — find how the app enters the context the shot needs (selecting a project / workspace / org / etc.). You'll drive it with the capture *scope* (below), not by clicking "the first one".
+4. **Data prerequisites** — determine what state the screen needs to look real (≥1 of something, a specific record, an open modal). This becomes both the placeholder's `prerequisites:` and a runtime guard (below).
+
+If a fact isn't in the source, do not fabricate it.
+
+## Capture scope — enter a KNOWN context, deterministically
+
+The capture profile declares a generic `scope` (key→value) for the prepared demo context — e.g. `{project: "Docs Demo"}`, or `{project, workspace, language}`, or `{org}` — whatever THIS product scopes by (you learned that by reading the source; it is not always "project"). The CLI injects it; read it with the `captureScope()` / `scopeValue(key)` helpers.
+
+- Select the context using the scope value (e.g. the project whose name === `scope.project`), via the selection mechanism you read from the source — **not** `.first()`.
+- Fall back to `.first()` ONLY when the relevant scope key is unset, so single-context setups still work.
+
+## Data prerequisites — skip clearly, don't time out
+
+If the data the shot needs is absent, a 15s selector timeout is a terrible error. Instead, guard it and skip with a reason that tells the user exactly what to stage:
+
+```typescript
+if ((await rows.count()) === 0) {
+  test.skip(true, 'Prerequisite not met: needs ≥1 suite in project "' + (scopeValue('project') ?? '<scope>') + '". Stage it, then re-run.');
+}
+```
+
+The skip reason MUST match what you wrote in the placeholder's `prerequisites:` line — they're the same fact, surfaced two ways.
 
 ## Spec template
 
 ```typescript
 import { test } from '@playwright/test';
-import { waitPastLogin, dumpAnnotations, type Placeholder } from 'document360-capture/helpers';
+import { waitPastLogin, dumpAnnotations, captureScope, scopeValue, type Placeholder } from 'document360-capture/helpers';
 
 const PLACEHOLDER: Placeholder = {
   id: '<placeholder.id>',
   saveTo: '<placeholder.save-to>',
-  highlight: [
-    // one stable selector per placeholder.highlight entry
-  ],
-  annotations: [
-    // { target: '<stable selector>', label: '1', text: '<short text>' }
-  ],
-  redact: [
-    // one stable selector per placeholder.redact entry
-  ],
+  highlight: [ /* one stable selector per placeholder.highlight entry */ ],
+  annotations: [ /* { target: '<stable selector>', label: '1', text: '<short text>' } */ ],
+  redact: [ /* one stable selector per placeholder.redact entry */ ],
 };
 
 test('<placeholder.id>', async ({ page }) => {
   await page.goto(process.env.CAPTURE_START_URL!);
   await waitPastLogin(page, new RegExp(process.env.CAPTURE_AUTH_BOUNDARY!));
 
-  // Translated from placeholder.steps — one Playwright action per step.
-  // Use STABLE selectors only.
-  // ...
+  // 1. Enter the prepared context using the scope (selection mechanism read from source).
+  const scope = captureScope();
+  // …select the context by scope.<key>; fall back to first only when that key is unset…
+
+  // 2. Navigate using the EXACT route read from the router (never a guessed path).
+  // …
+
+  // 3. Prerequisite guard — skip with a clear reason instead of timing out.
+  // if ((await <rows>.count()) === 0) test.skip(true, 'Prerequisite not met: …');
 
+  // 4. Reach the target state, settle, capture.
   await page.waitForSelector('<target state selector>', { state: 'visible' });
   await page.waitForTimeout(500);
-
   await page.locator('<capture target selector>').screenshot({ path: PLACEHOLDER.saveTo });
   await dumpAnnotations(page, PLACEHOLDER);
 });
@@ -46,31 +72,27 @@ test('<placeholder.id>', async ({ page }) => {
 
 ## Selector quality rule (non-negotiable)
 
-Use stable selectors in this priority order:
-
+Stable selectors in priority order:
 1. `[data-testid="..."]` — best.
 2. `[aria-label="..."]` — good.
-3. `<role>:has-text("...")` / `role=button[name="..."]` — acceptable when unique.
-4. Visible text (`text=...`, `:has-text(...)`) — acceptable for top-level nav and unique buttons.
+3. `role=button[name="..."]` / `<role>:has-text("...")` — acceptable when unique.
+4. Visible text (`text=...`) — acceptable for top-level nav and unique buttons.
 
-**Never** use CSS classes, `nth-child`, deep DOM paths, or auto-generated IDs (`#mui-12345`).
+**Never** CSS classes, `nth-child`, structural `li`/`div.x`, deep DOM paths, or auto-generated IDs (`#mui-12345`).
 
-## TODO escape hatch (when stable selectors don't exist)
-
-If a required interaction has no stable selector, do NOT write a fragile one. Instead:
+## TODO escape hatch (when a stable selector truly doesn't exist)
 
+Don't write a fragile selector. Instead:
 1. Use `test.skip(...)` instead of `test(...)`.
-2. Add a top-of-file comment: `// TODO: add data-testid="<suggested-name>" to <ComponentName> at <src/.../File.tsx>. Capture spec disabled until then.`
-3. Tell the user which file + component to fix, plus the `data-testid` value you'd recommend.
-
-The manual intern path in the placeholder still works — only the automated capture is blocked.
+2. Top-of-file comment: `// TODO: add data-testid="<name>" to <Component> at <src/.../File.tsx>. Capture disabled until then.`
+3. Tell the user which file + component to fix and the `data-testid` to add.
 
 ## Capture region (the placeholder's `capture` field)
 
 | `capture` value | Spec uses |
 |---|---|
 | `full-page` | `await page.screenshot({ path, fullPage: true })` |
-| `main-panel` | a stable container selector (read it from the project's main layout source) |
+| `main-panel` | a stable container selector (read it from the layout source) |
 | `modal-only` | `page.locator('[role="dialog"]').first().screenshot(...)` |
 | `panel-left` / `panel-right` | the project's named-panel selector |
 | `sidebar` | the project's sidebar selector |
@@ -78,8 +100,9 @@ The manual intern path in the placeholder still works — only the automated cap
 ## After writing the spec
 
 - Report the spec's path.
-- If you used the TODO escape hatch, surface the blocking selectors so the dev can fix them in one pass.
-- Remind the user how to capture it (screenshots are a separate tool — `document360-capture` is not bundled with the writer):
+- List anything that needs the user: the `data-testid`s a dev must add (TODO hatch), and the **data prerequisites** to stage (project/workspace + the records each shot needs).
+- Remind how to capture (screenshots are a separate tool — not bundled with the writer):
   1. First time only: `npm i -g document360-capture`
-  2. Once per machine: `d360-capture auth --profile <name>`
-  3. `d360-capture capture <id>` to take the screenshot.
+  2. Set the capture `scope` for the prepared demo context in `.d360-capture.json`.
+  3. Once per machine: `d360-capture auth --profile <name>`
+  4. `d360-capture capture <id>`.