@selvakumaresra/specship 0.3.0 → 0.5.0

package/dist/designer/file-panel.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPEN_FILES_PANEL_EXPR = void 0;
+// Opener for claude.ai/design's "Design Files" panel, shared by BOTH the live
+// listFilesDetailed scrape (designer-controller) and the session.fileListScrape
+// health anchor (ui-anchors) — one source so the probe exercises the exact path
+// production runs. They diverged once and the probe went green while production
+// silently no-op'd (PR #77 Codex P2); a shared constant prevents a repeat.
+//
+// Open-state is decided ONLY from the trigger's aria-expanded — the one reliable
+// signal. Two tempting alternatives are dead ends Codex walked us through (PR #77):
+//   - a blind label.click() TOGGLES an already-open panel shut, and iterate()
+//     calls listFiles() before+after a generation, so the second scrape reads the
+//     bare page and corrupts newFiles/removedFiles;
+//   - counting filename-like body text to infer "already open" can't tell a real
+//     panel row from a filename mentioned in a chat turn (index.html), so it
+//     skips opening and scrapes incidental text.
+// So: if the trigger exposes aria-expanded, obey it (open iff 'false'). If it
+// does NOT, leave the panel as-is — never a blind toggle, never a body-text
+// guess; the scrape then reads whatever is already visible (the long-standing
+// behavior). React attaches handlers via root delegation, so element.onclick is
+// null on the trigger — we click the label (the event bubbles to the delegated
+// handler) rather than walking up for a non-null .onclick (which never fires).
+//
+// Returns true when the "Design Files" label is present (opened or already-open
+// or left-as-is), false when it isn't found.
+exports.OPEN_FILES_PANEL_EXPR = `(() => {
+  const spans = Array.from(document.querySelectorAll('span'));
+  const label = spans.find((s) => s.children.length === 0 && (s.textContent || '').trim() === 'Design Files');
+  if (!label) return false;
+  let t = label;
+  for (let i = 0; i < 4 && t; i++) {
+    const ex = t.getAttribute && t.getAttribute('aria-expanded');
+    if (ex === 'true') return true;
+    if (ex === 'false') { label.click(); return true; }
+    t = t.parentElement;
+  }
+  return true;
+})()`;

package/dist/designer/interstitials.js

@@ -0,0 +1,97 @@
+"use strict";
+// Interstitial detection for claude.ai/design.
+//
+// The 2026-06 design UI interrupts the automated flow with content-only overlays
+// that carry no stable data-testid or ARIA role — they can only be matched by
+// their visible content. Each verb runs a pre-flight (DesignerController.
+// clearInterstitials, wired through ensureReady) so automation doesn't silently
+// stall on a banner, misread a frozen view as "done", or call a transient error
+// a context ceiling. Captured live 2026-06-19 against Chrome 149.
+//
+// Detection lives here — pure and unit-tested — so the copy heuristics have one
+// source of truth; the DOM/CDP glue (probe + click/reload/wait) stays in the
+// controller. This mirrors preview-host.ts / run-state.ts: classify in a tested
+// module, act in the controller.
+//
+// STRUCTURAL GUARD (review #1): the two TAKEOVER kinds (cloudflare,
+// transient-error) replace the whole app shell, so they're classified ONLY when
+// the shell is gone — `appShellPresent === false`. Without this, a design session
+// whose chat transcript mentions "verify you are human" (an auth/CAPTCHA mockup)
+// or "something went wrong … try again" (a Claude apology) would be misread as a
+// real overlay and hard-block every verb. The token banner is benign (it sits
+// over a live shell) and is gated on its own action button instead.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTINUE_HERE_TEXT = exports.TOKEN_BANNER_RE = exports.TRANSIENT_ERROR_BUTTON_RE = exports.TRANSIENT_ERROR_RE = exports.CLOUDFLARE_RE = exports.INTERSTITIAL_PROBE_EXPR = void 0;
+exports.classifyInterstitial = classifyInterstitial;
+exports.plannedAction = plannedAction;
+exports.isBlockingInterstitial = isBlockingInterstitial;
+// A single DOM read producing the InterstitialProbe shape. Exported as the ONE
+// source so the live pre-flight (designer-controller) and the CI diagnostic
+// (ci-health) probe identically — including the appShellPresent guard (review
+// #5 / below-gate dedup). Evaluated via browser.evalValue.
+exports.INTERSTITIAL_PROBE_EXPR = `(() => ({
+  bodyText: ((document.body && document.body.innerText) || '').slice(0, 20000),
+  buttonTexts: Array.from(document.querySelectorAll('button'))
+    .map((b) => (b.textContent || '').trim())
+    .filter(Boolean)
+    .slice(0, 300),
+  appShellPresent: !!document.querySelector('[data-testid="chat-composer-input"], [data-testid="chat-messages"]')
+}))()`;
+// Cloudflare bot-check / "verify you are human" takeover. The most blocking of
+// the three — it replaces the app shell and can't be auto-solved, only waited
+// out (it often self-clears) or handed to a human.
+exports.CLOUDFLARE_RE = /verify you are human|performing security verification|review the security of your connection|checking your browser before|needs to review the security/i;
+// Transient "Something went wrong" error page. Gated on app-shell-absence AND a
+// real action button (review #1) so an inline "something went wrong" string in
+// the transcript can't trip a reload storm.
+exports.TRANSIENT_ERROR_RE = /something went wrong/i;
+exports.TRANSIENT_ERROR_BUTTON_RE = /^(try again|back to projects)$/i;
+// Context-save nudge: "Start a new chat to save 483k tokens of context" with
+// New chat / Continue here. We click "Continue here" to keep the session's
+// context — "New chat" would discard it.
+exports.TOKEN_BANNER_RE = /start a new chat to save\b|save \d+k tokens of context/i;
+exports.CONTINUE_HERE_TEXT = 'Continue here';
+function hasButtonText(buttonTexts, text) {
+    const want = text.trim().toLowerCase();
+    return buttonTexts.some((t) => (t || '').trim().toLowerCase() === want);
+}
+function hasButtonMatching(buttonTexts, re) {
+    return buttonTexts.some((t) => re.test((t || '').trim()));
+}
+/**
+ * Classify the most pressing interstitial present, or null when the page is
+ * clear. Order is by severity: a Cloudflare takeover hides everything beneath
+ * it, so it's checked first; the token banner is the most benign (the composer
+ * stays usable beneath it) so it's checked last. Takeover kinds require the app
+ * shell to be ABSENT (see module header); the token banner requires its action
+ * button to be present (the phrase alone — e.g. echoed in chat — is not enough).
+ */
+function classifyInterstitial(probe, opts = {}) {
+    const body = probe.bodyText || '';
+    const buttons = probe.buttonTexts || [];
+    if (!probe.appShellPresent) {
+        if (exports.CLOUDFLARE_RE.test(body))
+            return 'cloudflare';
+        if (exports.TRANSIENT_ERROR_RE.test(body) && hasButtonMatching(buttons, exports.TRANSIENT_ERROR_BUTTON_RE))
+            return 'transient-error';
+    }
+    if (exports.TOKEN_BANNER_RE.test(body) && hasButtonText(buttons, opts.continueHere || exports.CONTINUE_HERE_TEXT))
+        return 'token-banner';
+    return null;
+}
+/** The handling strategy for each interstitial kind. */
+function plannedAction(kind) {
+    switch (kind) {
+        case 'token-banner':
+            return 'click-continue';
+        case 'transient-error':
+            return 'reload';
+        case 'cloudflare':
+            return 'await-human';
+    }
+}
+/** Blocking interstitials make a verb impossible; the token banner does not
+ *  (the shell stays usable beneath it), so a residual one is never fatal. */
+function isBlockingInterstitial(kind) {
+    return kind !== 'token-banner';
+}

package/dist/designer/oopif-reader.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OopifHtmlReader = void 0;
+exports.captureOopifHtml = captureOopifHtml;
+const cdp_trace_1 = require("./cdp-trace");
+const preview_host_1 = require("./preview-host");
+function evaluatedString(result) {
+    const rec = (0, cdp_trace_1.asRec)(result);
+    // An exceptionDetails means the evaluate threw — treat as no value.
+    if (rec.exceptionDetails)
+        return null;
+    const inner = (0, cdp_trace_1.asRec)(rec.result);
+    return typeof inner.value === 'string' && inner.value.length > 0 ? inner.value : null;
+}
+// Pick the preview child. The project renders its preview in a SINGLE OOPIF, so a
+// unique preview-host child is unambiguously THE preview. Zero, or many (e.g. old
+// and new preview coexisting during a file switch), -> null, so we never serve an
+// arbitrary or stale frame as the requested file (PR #67 review).
+//
+// NOTE (live-verified): the OOPIF *document* URL is per-file
+// (`…claudeusercontent.com/.../serve/<filename>?…`) — the `_bootstrap` is only the
+// iframe element's src; the loader navigates the frame to the real serve URL. So
+// matching the child against getIframeSrc() (`_bootstrap`) is wrong; host+uniqueness
+// is the correct signal. A future multi-preview disambiguation can match the active
+// file via that `/serve/<filename>` path, but single-preview is the steady state.
+function pickPreviewChild(children, isPreviewUrl) {
+    // type === 'iframe' guards against a same-origin worker/service-worker on
+    // claudeusercontent.com counting as a second "preview" and flooring the read to
+    // null (#67 review) — the preview is an iframe document, not a worker target.
+    const previews = children.filter((c) => typeof c.url === 'string' && c.type === 'iframe' && isPreviewUrl(c.url));
+    const only = previews[0];
+    return previews.length === 1 && only ? only : null;
+}
+/**
+ * PURE orchestrator for reading a cross-origin preview OOPIF's rendered HTML.
+ * Owns the CDP command sequence but not the socket; every call is timeout-bounded
+ * and bounded polling uses opts.now. Returns the serialized outerHTML string, or
+ * null on no-match / no-value / timeout / any throw — never throws, never hangs.
+ */
+async function captureOopifHtml(send, opts) {
+    const now = opts.now ?? (() => Date.now());
+    const waitForAttachMs = opts.waitForAttachMs ?? 1500;
+    const pollMs = opts.pollMs ?? 25;
+    const sendTimeoutMs = opts.sendTimeoutMs ?? 4000;
+    // Bound every CDP call: a live-but-silent socket must degrade to null, not hang
+    // forever (PR #67 review). A synchronous throw from `send` becomes a rejection.
+    const sendBounded = (method, params, sessionId) => {
+        let timer;
+        const timeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new Error('cdp-send-timeout')), sendTimeoutMs);
+        });
+        const call = (async () => send(method, params, sessionId))();
+        return Promise.race([call, timeout]).finally(() => clearTimeout(timer));
+    };
+    let armed = false;
+    try {
+        // (a) arm auto-attach. flatten:true is LOAD-BEARING — without it Chrome routes
+        // child traffic via the deprecated nested sendMessageToTarget the base send()
+        // does not speak. waitForDebuggerOnStart:false so OOPIFs aren't paused.
+        await sendBounded('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: false, flatten: true });
+        armed = true;
+        // (b) bounded-poll the injected snapshot for the unique preview child.
+        const deadline = now() + waitForAttachMs;
+        let child = pickPreviewChild(opts.attachedTargets(), opts.isPreviewUrl);
+        while (!child && now() < deadline) {
+            await new Promise((r) => setTimeout(r, pollMs));
+            child = pickPreviewChild(opts.attachedTargets(), opts.isPreviewUrl);
+        }
+        if (!child)
+            return null;
+        // (c) PRIMARY: DOM serialization on the CHILD session. No page-world execution
+        // context to depend on or be spoofed by; DOM.getDocument implicitly enables the
+        // DOM domain, and depth:0 fetches just the root node before getOuterHTML
+        // serializes the tree.
+        try {
+            const doc = (0, cdp_trace_1.asRec)(await sendBounded('DOM.getDocument', { depth: 0, pierce: false }, child.sessionId));
+            const root = (0, cdp_trace_1.asRec)(doc.root);
+            const nodeId = typeof root.nodeId === 'number' ? root.nodeId : null;
+            if (nodeId !== null) {
+                const outer = (0, cdp_trace_1.asRec)(await sendBounded('DOM.getOuterHTML', { nodeId }, child.sessionId));
+                if (typeof outer.outerHTML === 'string' && outer.outerHTML.length > 0)
+                    return outer.outerHTML;
+            }
+        }
+        catch {
+            // fall through to the Runtime fallback
+        }
+        // (d) FALLBACK: page-world Runtime.evaluate on the CHILD sessionId (without it
+        // the eval runs in the parent page and returns the shell). For builds/states
+        // where the DOM route returns nothing.
+        const evalRes = await sendBounded('Runtime.evaluate', { expression: 'document.documentElement.outerHTML', returnByValue: true, awaitPromise: false }, child.sessionId);
+        return evaluatedString(evalRes);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        // (e) bounded, self-contained teardown — never let cleanup throw or hang.
+        if (armed) {
+            try {
+                await sendBounded('Target.setAutoAttach', { autoAttach: false, waitForDebuggerOnStart: false, flatten: true });
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+}
+class OopifHtmlReader extends cdp_trace_1.CdpSession {
+    // Keyed by sessionId; each entry also carries targetId for targetInfoChanged.
+    childTargets = new Map();
+    constructor(ws, target, opts = {}) {
+        // One-shot reader: PIN reconnect:false (a mid-capture gap degrades to null ->
+        // node-fetch fallback; there is no one-shot terminal to recover). Pinned last
+        // so a caller can't accidentally route the base reconnect path into the no-op
+        // enableDomains() (#67 review, below-gate).
+        super(ws, target, { ...opts, reconnect: false });
+    }
+    static async attach(opts = {}) {
+        if (typeof WebSocket === 'undefined')
+            return null;
+        try {
+            const { ws, target } = await OopifHtmlReader.connectTarget(opts);
+            return new OopifHtmlReader(ws, target, opts);
+        }
+        catch {
+            return null;
+        }
+    }
+    // No Network.enable for a one-shot OOPIF read; captureOopifHtml issues the
+    // Target.setAutoAttach itself so the pure unit owns the full sequence.
+    async enableDomains() { }
+    onEvent(method, params, _sessionId) {
+        const p = (0, cdp_trace_1.asRec)(params);
+        if (method === 'Target.attachedToTarget') {
+            const sessionId = typeof p.sessionId === 'string' ? p.sessionId : '';
+            const info = (0, cdp_trace_1.asRec)(p.targetInfo);
+            const url = typeof info.url === 'string' ? info.url : '';
+            const type = typeof info.type === 'string' ? info.type : '';
+            const targetId = typeof info.targetId === 'string' ? info.targetId : undefined;
+            if (sessionId)
+                this.childTargets.set(sessionId, { sessionId, url, type, targetId });
+            return;
+        }
+        if (method === 'Target.targetInfoChanged') {
+            // A child can attach as about:blank then navigate to _bootstrap (would be a
+            // false null), or attach as _bootstrap then navigate away (would be stale
+            // wrong-content). Keep the stored URL current, correlated by targetId (#67).
+            const info = (0, cdp_trace_1.asRec)(p.targetInfo);
+            const targetId = typeof info.targetId === 'string' ? info.targetId : '';
+            if (!targetId)
+                return;
+            for (const child of this.childTargets.values()) {
+                if (child.targetId === targetId) {
+                    if (typeof info.url === 'string')
+                        child.url = info.url;
+                    if (typeof info.type === 'string')
+                        child.type = info.type;
+                }
+            }
+            return;
+        }
+        if (method === 'Target.detachedFromTarget') {
+            const sessionId = typeof p.sessionId === 'string' ? p.sessionId : '';
+            if (sessionId)
+                this.childTargets.delete(sessionId);
+        }
+    }
+    async readPreviewHtml() {
+        return captureOopifHtml(this.send.bind(this), {
+            attachedTargets: () => [...this.childTargets.values()],
+            isPreviewUrl: preview_host_1.isPreviewIframeSrc
+        });
+    }
+}
+exports.OopifHtmlReader = OopifHtmlReader;

package/dist/designer/package-meta.js

@@ -0,0 +1,18 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PACKAGE_VERSION = exports.PACKAGE_METADATA = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const repo_root_1 = require("./repo-root");
+function readPackageMetadata() {
+    const raw = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(repo_root_1.REPO_ROOT, 'package.json'), 'utf8'));
+    return {
+        name: typeof raw.name === 'string' ? raw.name : 'designer',
+        version: typeof raw.version === 'string' ? raw.version : '0.0.0'
+    };
+}
+exports.PACKAGE_METADATA = readPackageMetadata();
+exports.PACKAGE_VERSION = exports.PACKAGE_METADATA.version;

package/dist/designer/preview-host.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPreviewIframeSrc = isPreviewIframeSrc;
+exports.previewIframeVariant = previewIframeVariant;
+exports.isBootstrapShellHtml = isBootstrapShellHtml;
+// The design preview iframe is a load-bearing invariant: it must serve from
+// claudeusercontent.com. How it's addressed has drifted — the legacy form was
+// `claudeusercontent.com/...?t=<signed-token>`; the 2026-06 redesign (issue #61)
+// moved it to a per-project `<uuid>.claudeusercontent.com/_bootstrap...` subdomain
+// with no token. Assert the HOST (real drift = the preview leaving that domain),
+// not a substring — a substring match would wave through a suffix-attached host
+// (`claudeusercontent.com.evil.test`) or a query/path mention
+// (`evil.test/?u=claudeusercontent.com`), defeating the drift anchor this backs.
+function isPreviewIframeSrc(src) {
+    let host;
+    try {
+        host = new URL(src).hostname;
+    }
+    catch {
+        return false;
+    }
+    return host === 'claudeusercontent.com' || host.endsWith('.claudeusercontent.com');
+}
+// Which addressing scheme the (already host-validated) preview src uses. Reported
+// in the health anchor's detail so drift between the legacy signed-token form and
+// the current per-project bootstrap subdomain stays legible.
+function previewIframeVariant(src) {
+    if (/[?&]t=/.test(src))
+        return 'signed-token';
+    if (/\/_bootstrap/.test(src))
+        return 'bootstrap-subdomain';
+    return 'other';
+}
+// True when `html` is the unauthenticated ~1.1KB loader shell the bootstrap
+// iframe serves to the parent origin (not the rendered design). A node fetch of a
+// bootstrap-subdomain src always returns this shell; the real DOM only exists in
+// the cross-origin OOPIF (see oopif-reader.ts). The shell's stable signature is
+// its postMessage init handshake ('omelette-preview-init') — class/markup hashes
+// drift, that string does not. Used to assert the OOPIF read returned rendered
+// content, not the loader, and to defend callers against saving a shell as the
+// captured artifact. Empty / non-shell HTML → false (don't misread "no sample").
+//
+// Size-bounded (review below-gate): a rendered design that legitimately
+// DOCUMENTS the preview protocol could contain the marker string, so require the
+// document also be loader-sized. The real shell is ~1.1KB; any rendered design is
+// far larger, so the marker + a sub-4KB body is an unambiguous shell signal.
+const BOOTSTRAP_SHELL_MAX_BYTES = 4000;
+function isBootstrapShellHtml(html) {
+    return typeof html === 'string' && html.length < BOOTSTRAP_SHELL_MAX_BYTES && html.includes('omelette-preview-init');
+}

package/dist/designer/repo-root.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPO_ROOT = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// Walk up from this file's location until we find package.json. Lets the
+// vendored designer subtree locate its shipped resource (selectors.json) at
+// the SpecShip install root regardless of layout:
+//   - source mode: repo-root.ts at src/designer/ → walks up to the repo root.
+//   - compiled mode (tsc → dist/designer/): repo-root.js → walks up past
+//     dist/ to the dir holding SpecShip's package.json (the install root).
+//
+// Uses CommonJS `__dirname` — this subtree compiles to CJS under
+// src/designer/tsconfig.json, so there is no `import.meta` to reconcile with
+// SpecShip's `module: commonjs` toolchain.
+function findRepoRoot() {
+    let dir = __dirname;
+    for (let i = 0; i < 8; i++) {
+        if (node_fs_1.default.existsSync(node_path_1.default.join(dir, 'package.json')))
+            return dir;
+        const parent = node_path_1.default.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error('repo-root: could not find package.json walking up from ' + __dirname);
+}
+exports.REPO_ROOT = findRepoRoot();