@solidxai/core 0.1.15 → 0.1.16-beta.1

package/src/testing/adapters/ui/playwright-adapter.ts

@@ -1,28 +1,73 @@
-import type { Browser, BrowserContext, Page } from "playwright";
+import type { Browser, BrowserContext, Page, ConsoleMessage, Response, Request } from "playwright";
 
-import type { PlaywrightAdapterOptions } from "./ui.types";
+import type { CaptureOptions, PlaywrightAdapterOptions } from "./ui.types";
 
 function isAbsoluteUrl(url: string): boolean {
   return /^https?:\/\//i.test(url);
 }
 
 export const DEFAULT_UI_TIMEOUT_MS = 30_000;
+/** Keep the buffers bounded so a chatty page can't grow memory without limit. */
+const MAX_CONSOLE_ENTRIES = 500;
+const MAX_NETWORK_ENTRIES = 500;
+const MAX_NETWORK_BODY_CHARS = 16_000;
+const STATIC_EXT_RE = /\.(?:css|js|mjs|cjs|map|png|jpe?g|gif|svg|ico|webp|avif|woff2?|ttf|eot|otf|mp4|webm|mp3|wav|pdf|zip)$/i;
+
+export interface ConsoleLogEntry {
+  type: string;
+  text: string;
+  location?: string;
+}
+
+export interface NetworkLogEntry {
+  method: string;
+  url: string;
+  resourceType?: string;
+  requestHeaders?: Record<string, string>;
+  requestBody?: string;
+  status?: number;
+  ok?: boolean;
+  responseHeaders?: Record<string, string>;
+  responseBody?: string;
+  durationMs?: number;
+  failure?: string;
+}
+
+/** One artifact to hand to the reporter's `attach()` on scenario failure. */
+export interface FailureArtifact {
+  name: string;
+  contentType: string;
+  data: Buffer | string;
+}
 
 export class PlaywrightAdapter {
   private readonly baseUrl?: string;
   private readonly headless: boolean;
   private readonly defaultTimeoutMs: number;
   private readonly navigationTimeoutMs: number;
+  private readonly capture: CaptureOptions;
+  private readonly recordVideo: boolean;
   private browser?: Browser;
   private context?: BrowserContext;
   public page?: Page;
 
+  /** Per-scenario ring buffers; reset via {@link resetCapture} at each scenario start. */
+  private consoleBuf: ConsoleLogEntry[] = [];
+  private networkBuf: NetworkLogEntry[] = [];
+
+  /** Whole-run video: temp dir Playwright writes the webm into, and the finalized bytes. */
+  private videoDir?: string;
+  private runVideo?: FailureArtifact;
+  private readonly requestStartedAt = new Map<Request, number>();
+
   constructor(opts?: PlaywrightAdapterOptions) {
     this.baseUrl = opts?.baseUrl;
     this.headless = opts?.headless ?? true;
     this.defaultTimeoutMs = opts?.defaultTimeoutMs ?? DEFAULT_UI_TIMEOUT_MS;
     this.navigationTimeoutMs =
       opts?.navigationTimeoutMs ?? this.defaultTimeoutMs;
+    this.capture = opts?.capture ?? {};
+    this.recordVideo = opts?.recordVideo ?? true;
   }
 
   isHeadless(): boolean {
@@ -48,13 +93,158 @@ export class PlaywrightAdapter {
   async start(): Promise<void> {
     const { chromium } = await import('playwright');
     this.browser = await chromium.launch({ headless: this.headless });
-    this.context = await this.browser.newContext();
+    // Record a whole-run video only when this run enables it; it is still only KEPT when
+    // the run fails (see stop({ keepVideo }) / the runner). The temp dir has to exist
+    // before the context is created, since recordVideo is a context-creation option.
+    if (this.recordVideo) {
+      const os = await import('os');
+      const path = await import('path');
+      const fs = await import('fs');
+      this.videoDir = fs.mkdtempSync(path.join(os.tmpdir(), 'solid-run-video-'));
+    }
+    this.context = await this.browser.newContext(
+      this.videoDir ? { recordVideo: { dir: this.videoDir } } : {},
+    );
     this.context.setDefaultTimeout(this.defaultTimeoutMs);
     this.context.setDefaultNavigationTimeout(this.navigationTimeoutMs);
     this.page = await this.context.newPage();
+    this.attachCaptureListeners(this.page);
+  }
+
+  /** Whole-run video, available after {@link stop} has finalized the recording. */
+  getRunVideo(): FailureArtifact | undefined {
+    return this.runVideo;
+  }
+
+  /**
+   * Wire console/network listeners once per page. Events accumulate in the per-scenario
+   * buffers and are only surfaced (via {@link collectFailureArtifacts}) when a scenario
+   * fails — passing scenarios reset and discard them.
+   */
+  private attachCaptureListeners(page: Page): void {
+    if (this.capture.console) {
+      page.on("console", (msg: ConsoleMessage) => {
+        if (this.consoleBuf.length >= MAX_CONSOLE_ENTRIES) return;
+        const loc = msg.location();
+        this.consoleBuf.push({
+          type: msg.type(),
+          text: msg.text(),
+          location: loc?.url ? `${loc.url}:${loc.lineNumber ?? 0}` : undefined,
+        });
+      });
+      page.on("pageerror", (err: Error) => {
+        if (this.consoleBuf.length >= MAX_CONSOLE_ENTRIES) return;
+        this.consoleBuf.push({ type: "pageerror", text: err?.stack || err?.message || String(err) });
+      });
+    }
+
+    if (this.capture.network) {
+      page.on("request", (req: Request) => {
+        this.requestStartedAt.set(req, Date.now());
+      });
+      page.on("response", async (res: Response) => {
+        if (this.networkBuf.length >= MAX_NETWORK_ENTRIES) return;
+        const req = res.request();
+        const captureDetail = shouldCaptureDetailedNetworkEntry(req);
+        const requestHeaders = captureDetail ? await req.allHeaders().catch(() => undefined) : undefined;
+        const responseHeaders = captureDetail ? await res.allHeaders().catch(() => undefined) : undefined;
+        const responseBody = captureDetail ? await this.readResponseBody(res, responseHeaders) : undefined;
+        const startedAt = this.requestStartedAt.get(req);
+        this.requestStartedAt.delete(req);
+        this.networkBuf.push({
+          method: req.method(),
+          url: res.url(),
+          resourceType: req.resourceType(),
+          requestHeaders,
+          requestBody: captureDetail ? truncateText(req.postData() ?? undefined) : undefined,
+          status: res.status(),
+          ok: res.ok(),
+          responseHeaders,
+          responseBody,
+          durationMs: startedAt != null ? Date.now() - startedAt : undefined,
+        });
+      });
+      page.on("requestfailed", async (req: Request) => {
+        if (this.networkBuf.length >= MAX_NETWORK_ENTRIES) return;
+        const startedAt = this.requestStartedAt.get(req);
+        this.requestStartedAt.delete(req);
+        const captureDetail = shouldCaptureDetailedNetworkEntry(req);
+        this.networkBuf.push({
+          method: req.method(),
+          url: req.url(),
+          resourceType: req.resourceType(),
+          requestHeaders: captureDetail ? await req.allHeaders().catch(() => undefined) : undefined,
+          requestBody: captureDetail ? truncateText(req.postData() ?? undefined) : undefined,
+          failure: req.failure()?.errorText ?? "request failed",
+          durationMs: startedAt != null ? Date.now() - startedAt : undefined,
+        });
+      });
+    }
+  }
+
+  /** Clear the per-scenario buffers. Called by the engine at each scenario start. */
+  resetCapture(): void {
+    this.consoleBuf = [];
+    this.networkBuf = [];
+    this.requestStartedAt.clear();
+  }
+
+  getConsoleLog(): ConsoleLogEntry[] {
+    return this.consoleBuf;
+  }
+
+  getNetworkLog(): NetworkLogEntry[] {
+    return this.networkBuf;
+  }
+
+  private async readResponseBody(res: Response, headers?: Record<string, string>): Promise<string | undefined> {
+    const contentType = String(headers?.["content-type"] ?? headers?.["Content-Type"] ?? "").toLowerCase();
+    const contentLength = Number(headers?.["content-length"] ?? headers?.["Content-Length"] ?? 0);
+    if (contentLength && contentLength > MAX_NETWORK_BODY_CHARS) {
+      return `[body omitted: ${contentLength} bytes]`;
+    }
+    if (!isTextLikeContentType(contentType)) return undefined;
+    try {
+      return truncateText(await res.text());
+    } catch {
+      return undefined;
+    }
   }
 
-  async stop(): Promise<void> {
+  /**
+   * Build the text artifacts to attach when the current scenario has FAILED (console +
+   * network logs). Honors this adapter's capture flags. Returns an empty list when no page
+   * is open (e.g. an API scenario). Failure screenshots were removed — the whole-run video
+   * (kept only on failure) is the visual failure artifact now.
+   */
+  async collectFailureArtifacts(): Promise<FailureArtifact[]> {
+    if (!this.page) return [];
+    const artifacts: FailureArtifact[] = [];
+
+    if (this.capture.console && this.consoleBuf.length) {
+      artifacts.push({
+        name: "console.json",
+        contentType: "application/json",
+        data: JSON.stringify(this.consoleBuf),
+      });
+    }
+
+    if (this.capture.network && this.networkBuf.length) {
+      artifacts.push({
+        name: "network.json",
+        contentType: "application/json",
+        data: JSON.stringify(this.networkBuf),
+      });
+    }
+
+    return artifacts;
+  }
+
+  async stop(opts?: { keepVideo?: boolean }): Promise<void> {
+    const keepVideo = opts?.keepVideo ?? false;
+    // Grab the video handle before the context closes; its file is only finalized on close().
+    const video = this.videoDir ? this.page?.video() : undefined;
+
     try {
       if (this.context) {
         await this.context.close();
@@ -64,6 +254,25 @@ export class PlaywrightAdapter {
       this.page = undefined;
     }
 
+    if (video && this.videoDir) {
+      try {
+        const fs = await import('fs');
+        // Only read the recording into memory when the caller wants to keep it (i.e. the
+        // run FAILED). Passing runs discard the webm unread — no wasted IO/memory.
+        if (keepVideo) {
+          const videoPath = await video.path();
+          const data = await fs.promises.readFile(videoPath);
+          this.runVideo = { name: 'run.webm', contentType: 'video/webm', data };
+        }
+        // Clean up the temp recording directory either way.
+        await fs.promises.rm(this.videoDir, { recursive: true, force: true }).catch(() => {});
+      } catch {
+        // A video read failure must never mask the real run result.
+      } finally {
+        this.videoDir = undefined;
+      }
+    }
+
     try {
       if (this.browser) {
         await this.browser.close();
@@ -76,8 +285,49 @@ export class PlaywrightAdapter {
   resolveUrl(url: string): string {
     if (isAbsoluteUrl(url)) return url;
     if (this.baseUrl) {
-      return new URL(url, this.baseUrl).toString();
+      // Treat the configured base as a prefix and keep it whole, matching how
+      // the API adapter combines axios `baseURL` with a relative url. Resolving
+      // through `new URL()` follows RFC 3986 and discards any path on the base,
+      // so an application registered at https://host/myapp would send "/login"
+      // to https://host/login instead of https://host/myapp/login.
+      return `${this.baseUrl.replace(/\/+$/, "")}/${url.replace(/^\/+/, "")}`;
     }
     return url;
   }
 }
+
+function truncateText(value?: string): string | undefined {
+  if (!value) return undefined;
+  if (value.length <= MAX_NETWORK_BODY_CHARS) return value;
+  return `${value.slice(0, MAX_NETWORK_BODY_CHARS)}\n… [truncated ${value.length - MAX_NETWORK_BODY_CHARS} chars]`;
+}
+
+function isTextLikeContentType(contentType: string): boolean {
+  if (!contentType) return true;
+  return (
+    contentType.includes("json") ||
+    contentType.includes("text/") ||
+    contentType.includes("javascript") ||
+    contentType.includes("xml") ||
+    contentType.includes("html") ||
+    contentType.includes("x-www-form-urlencoded")
+  );
+}
+
+function shouldCaptureDetailedNetworkEntry(req: Request): boolean {
+  const resourceType = req.resourceType().toLowerCase();
+  if (resourceType === "xhr" || resourceType === "fetch") return true;
+
+  const method = req.method().toUpperCase();
+  if (method !== "GET" && method !== "HEAD") return true;
+
+  const url = req.url().toLowerCase();
+  try {
+    const pathname = new URL(url).pathname.toLowerCase();
+    if (STATIC_EXT_RE.test(pathname)) return false;
+  } catch {
+    if (STATIC_EXT_RE.test(url)) return false;
+  }
+
+  return resourceType === "document";
+}

package/src/testing/adapters/ui/ui.types.ts

@@ -1,6 +1,20 @@
+/**
+ * Per-run capture toggles for the Playwright adapter. Console/network events are
+ * buffered while a scenario runs and only flushed (attached to the reporter) when the
+ * scenario FAILS; passing scenarios discard them. API scenarios never open a page, so
+ * nothing is captured. The whole-run video may be enabled per run and is kept only when
+ * the run fails.
+ */
+export interface CaptureOptions {
+  console?: boolean;
+  network?: boolean;
+}
+
 export interface PlaywrightAdapterOptions {
   headless?: boolean;
   baseUrl?: string;
   defaultTimeoutMs?: number;
   navigationTimeoutMs?: number;
+  capture?: CaptureOptions;
+  recordVideo?: boolean;
 }

package/src/testing/contracts/runtime-context.types.ts

@@ -30,6 +30,12 @@ export interface TestContext {
   reporter: Reporter;
   specRegistry?: SpecRegistry;
   testData?: Record<string, Record<string, any>>;
+  env?: Record<string, string>;
+  /**
+   * Secrets referenced by this scenario, resolved server-side before the run.
+   * Scoped per scenario — a scenario never sees another scenario's secrets.
+   */
+  secrets?: Record<string, any>;
   options?: {
     printApiLogs?: boolean;
   };

package/src/testing/core/interpolation.ts

@@ -1,4 +1,5 @@
 import type { TestContext } from "../contracts/runtime-context.types";
+import { parsePathSegments } from "./path-segments";
 
 const TOKEN_REGEX = /\$\{([^}]+)\}/g;
 
@@ -13,74 +14,6 @@ function getByPath(obj: Record<string, any>, path: string): unknown {
   return current;
 }
 
-function parsePathSegments(path: string): string[] {
-  const segments: string[] = [];
-  let buffer = "";
-  let i = 0;
-
-  const pushBuffer = () => {
-    if (buffer) {
-      segments.push(buffer);
-      buffer = "";
-    }
-  };
-
-  while (i < path.length) {
-    const ch = path[i];
-    if (ch === ".") {
-      pushBuffer();
-      i += 1;
-      continue;
-    }
-    if (ch === "[") {
-      pushBuffer();
-      i += 1;
-      if (i >= path.length) break;
-      let quote = "";
-      if (path[i] === '"' || path[i] === "'") {
-        quote = path[i];
-        i += 1;
-      }
-      let value = "";
-      while (i < path.length) {
-        const c = path[i];
-        if (quote) {
-          if (c === "\\" && i + 1 < path.length) {
-            value += path[i + 1];
-            i += 2;
-            continue;
-          }
-          if (c === quote) {
-            i += 1;
-            break;
-          }
-          value += c;
-          i += 1;
-          continue;
-        }
-        if (c === "]") break;
-        value += c;
-        i += 1;
-      }
-      while (i < path.length && path[i] !== "]") {
-        i += 1;
-      }
-      if (i < path.length && path[i] === "]") {
-        i += 1;
-      }
-      if (value) {
-        segments.push(value);
-      }
-      continue;
-    }
-    buffer += ch;
-    i += 1;
-  }
-
-  pushBuffer();
-  return segments;
-}
-
 function getByPathWithBrackets(obj: Record<string, any>, path: string): unknown {
   if (!path) return undefined;
   const parts = parsePathSegments(path);
@@ -94,13 +27,50 @@ function getByPathWithBrackets(obj: Record<string, any>, path: string): unknown
 
 type TokenResolution = { value: unknown; raw: boolean };
 
+const SECRET_PREFIX = "secret:";
+
+/**
+ * Collects the secret keys referenced anywhere inside `value` — step args, headers,
+ * bodies — without depending on its shape. Used by the runner to resolve exactly the
+ * secrets a scenario needs, rather than loading the whole store into a run.
+ *
+ * Shares TOKEN_REGEX with the resolver deliberately: a second hand-written matcher is
+ * how the two drift, and drift means a scenario silently losing a secret it referenced.
+ */
+export function collectSecretKeys(value: unknown): string[] {
+  const keys = new Set<string>();
+  for (const match of JSON.stringify(value ?? null).matchAll(TOKEN_REGEX)) {
+    const token = match[1];
+    if (token.startsWith(SECRET_PREFIX)) {
+      const name = token.slice(SECRET_PREFIX.length);
+      if (name) keys.add(name);
+    }
+  }
+  return [...keys];
+}
+
 function resolveToken(token: string, ctx: TestContext): TokenResolution {
+  if (token.startsWith(SECRET_PREFIX)) {
+    const name = token.slice(SECRET_PREFIX.length);
+    if (!name) {
+      throw new Error('Invalid interpolation token: "secret:"');
+    }
+    // Resolved server-side into ctx.secrets before the run; never caller-supplied.
+    const value = ctx.secrets?.[name];
+    if (value === undefined) {
+      throw new Error(`Missing secret for token: "${token}"`);
+    }
+    // Secrets carry a declared valueType, so a json/number/boolean secret used as an
+    // exact token returns typed rather than stringified. Strings behave like env:.
+    return { value, raw: typeof value !== "string" };
+  }
+
   if (token.startsWith("env:")) {
     const name = token.slice("env:".length);
     if (!name) {
       throw new Error('Invalid interpolation token: "env:"');
     }
-    const value = process.env[name];
+    const value = ctx.env?.[name] ?? process.env[name];
     if (value === undefined) {
       throw new Error(`Missing env var for token: "${token}"`);
     }

package/src/testing/core/path-resolution.spec.ts

@@ -0,0 +1,133 @@
+// Purpose: lock down lookup-path parsing and token interpolation — the behaviours that decide
+// whether a scenario file's `${res:...}` / `${data:...}` references resolve or silently vanish.
+
+import type { TestContext } from "../contracts/runtime-context.types";
+import { interpolateDeep, interpolateString } from "./interpolation";
+import { parsePathSegments } from "./path-segments";
+import { SimpleResourceStore } from "./resource-store";
+
+function makeCtx(overrides: Partial<TestContext> = {}): TestContext {
+  return {
+    scenarioId: "spec",
+    scenarioType: "api",
+    params: {},
+    resources: new SimpleResourceStore(),
+    reporter: { onScenarioStart: () => {}, onStep: () => {}, onScenarioEnd: () => {} } as any,
+    ...overrides,
+  } as TestContext;
+}
+
+describe("parsePathSegments", () => {
+  it("treats dot and bracket notation as equivalent", () => {
+    expect(parsePathSegments("a.b.0.c")).toEqual(["a", "b", "0", "c"]);
+    expect(parsePathSegments("a.b[0].c")).toEqual(["a", "b", "0", "c"]);
+    expect(parsePathSegments('a["b"].c')).toEqual(["a", "b", "c"]);
+  });
+
+  it("keeps quoted keys containing spaces and punctuation intact", () => {
+    expect(parsePathSegments('book["Clean Code"].title')).toEqual(["book", "Clean Code", "title"]);
+    expect(parsePathSegments("book['a.b'].title")).toEqual(["book", "a.b", "title"]);
+  });
+
+  it("returns no segments for an empty path", () => {
+    expect(parsePathSegments("")).toEqual([]);
+  });
+});
+
+describe("SimpleResourceStore", () => {
+  function seeded() {
+    const store = new SimpleResourceStore();
+    store.set("createBook", {
+      status: 201,
+      bodyText: '{"data":{"title":"Clean Code"}}',
+      bodyJson: { data: { title: "Clean Code" }, result: [{ id: 7 }, { id: 8 }] },
+    });
+    return store;
+  }
+
+  it("resolves dot paths", () => {
+    expect(seeded().get("createBook.bodyJson.data.title")).toBe("Clean Code");
+    expect(seeded().get("createBook.status")).toBe(201);
+  });
+
+  it("resolves array elements by numeric segment", () => {
+    expect(seeded().get("createBook.bodyJson.result.0.id")).toBe(7);
+  });
+
+  it("resolves array elements by bracket index, equivalently", () => {
+    const store = seeded();
+    expect(store.get("createBook.bodyJson.result[0].id")).toBe(7);
+    expect(store.get("createBook.bodyJson.result[1].id")).toBe(8);
+    // the two spellings must agree — this asymmetry with ${data:...} was the original bug
+    expect(store.get("createBook.bodyJson.result[0].id")).toBe(
+      store.get("createBook.bodyJson.result.0.id"),
+    );
+  });
+
+  it("returns undefined for a missing path rather than throwing", () => {
+    expect(seeded().get("createBook.bodyJson.nope.deeper")).toBeUndefined();
+    expect(seeded().get("neverSaved")).toBeUndefined();
+  });
+
+  it("round-trips: anything readable by bracket path is also writable by one", () => {
+    const store = new SimpleResourceStore();
+    store.set('a["b c"].d', 42);
+    expect(store.get('a["b c"].d')).toBe(42);
+    expect(store.get("a.b c.d")).toBe(42);
+  });
+
+  it("has() follows get()", () => {
+    const store = seeded();
+    expect(store.has("createBook.bodyJson.result[0].id")).toBe(true);
+    expect(store.has("createBook.bodyJson.result[9].id")).toBe(false);
+  });
+});
+
+describe("interpolation", () => {
+  it("stringifies non-string ${res:...} values", () => {
+    const ctx = makeCtx();
+    ctx.resources.set("r", { status: 200, bodyJson: { id: 1 } });
+    // the whole object flattens to text — which is why assert.httpStatus `from` and
+    // assert.jsonPath `from` can never receive a live response object
+    expect(interpolateDeep("${res:r}", ctx)).toBe('{"status":200,"bodyJson":{"id":1}}');
+    // a scalar leaf survives intact, because the store walks the object before flattening
+    expect(interpolateDeep("${res:r.bodyJson.id}", ctx)).toBe("1");
+  });
+
+  it("resolves ${res:...} bracket paths", () => {
+    const ctx = makeCtx();
+    ctx.resources.set("r", { bodyJson: { result: [{ id: 7 }] } });
+    expect(interpolateDeep("${res:r.bodyJson.result[0].id}", ctx)).toBe("7");
+    expect(interpolateDeep("${res:r.bodyJson.result.0.id}", ctx)).toBe("7");
+  });
+
+  it("preserves the raw record for ${data:..._rec} only when it is the entire value", () => {
+    const ctx = makeCtx({ testData: { book: { CleanCode: { title: "Clean Code", pages: 464 } } } });
+    expect(interpolateDeep('${data:book["CleanCode"]._rec}', ctx)).toEqual({
+      title: "Clean Code",
+      pages: 464,
+    });
+    // embedded in a larger string it has to flatten, since the result must stay a string
+    expect(interpolateDeep('x ${data:book["CleanCode"]._rec}', ctx)).toBe(
+      'x {"title":"Clean Code","pages":464}',
+    );
+    expect(interpolateDeep('${data:book["CleanCode"].title}', ctx)).toBe("Clean Code");
+  });
+
+  it("resolves ${secret:...} and keeps it out of nothing else", () => {
+    const ctx = makeCtx({ secrets: { "test-username": "alice" } });
+    expect(interpolateDeep("${secret:test-username}", ctx)).toBe("alice");
+    expect(() => interpolateString("${secret:absent}", ctx)).toThrow(/Missing secret/);
+  });
+
+  it("throws a named error for an unsaved resource rather than yielding undefined", () => {
+    expect(() => interpolateString("${res:neverSaved.id}", makeCtx())).toThrow(/Missing resource/);
+  });
+
+  it("recurses through objects and arrays", () => {
+    const ctx = makeCtx({ params: { n: "1" } });
+    expect(interpolateDeep({ a: ["${params.n}", { b: "${params.n}" }] }, ctx)).toEqual({
+      a: ["1", { b: "1" }],
+    });
+  });
+});

package/src/testing/core/path-segments.ts

@@ -0,0 +1,81 @@
+// Purpose: shared lookup-path parsing for interpolation tokens and the resource store.
+
+/**
+ * Split a lookup path into segments, accepting dot and bracket notation interchangeably:
+ * `a.b.0.c`, `a.b[0].c` and `a["b"].c` all yield the same segments.
+ *
+ * Both `${data:...}` and `${res:...}` resolve through this, so the two token families share one
+ * path syntax. Previously only `${data:...}` parsed brackets while the resource store split on
+ * "." alone, which meant `${res:r.bodyJson.result[0].id}` silently resolved to nothing while the
+ * `${data:...}` form right next to it worked — the asymmetry was a standing authoring trap.
+ *
+ * Bracket contents may be quoted (`["Clean Code"]`) for keys containing spaces or punctuation;
+ * backslash escapes inside quotes are honoured. Empty brackets contribute no segment.
+ */
+export function parsePathSegments(path: string): string[] {
+  const segments: string[] = [];
+  let buffer = "";
+  let i = 0;
+
+  const pushBuffer = () => {
+    if (buffer) {
+      segments.push(buffer);
+      buffer = "";
+    }
+  };
+
+  while (i < path.length) {
+    const ch = path[i];
+    if (ch === ".") {
+      pushBuffer();
+      i += 1;
+      continue;
+    }
+    if (ch === "[") {
+      pushBuffer();
+      i += 1;
+      if (i >= path.length) break;
+      let quote = "";
+      if (path[i] === '"' || path[i] === "'") {
+        quote = path[i];
+        i += 1;
+      }
+      let value = "";
+      while (i < path.length) {
+        const c = path[i];
+        if (quote) {
+          if (c === "\\" && i + 1 < path.length) {
+            value += path[i + 1];
+            i += 2;
+            continue;
+          }
+          if (c === quote) {
+            i += 1;
+            break;
+          }
+          value += c;
+          i += 1;
+          continue;
+        }
+        if (c === "]") break;
+        value += c;
+        i += 1;
+      }
+      while (i < path.length && path[i] !== "]") {
+        i += 1;
+      }
+      if (i < path.length && path[i] === "]") {
+        i += 1;
+      }
+      if (value) {
+        segments.push(value);
+      }
+      continue;
+    }
+    buffer += ch;
+    i += 1;
+  }
+
+  pushBuffer();
+  return segments;
+}