{"record":{"id":"f1db76a054172233","repo":"garrytan/gstack","slug":"usage-frame-url-pattern","errorCode":null,"errorMessage":"Usage: frame --url <pattern>","messagePattern":"Usage: frame --url <pattern>","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"browse/src/meta-commands.ts","lineNumber":1018,"sourceCode":"    // ─── Frame ───────────────────────────────────────\n    case 'frame': {\n      const target = args[0];\n      if (!target) throw new Error('Usage: frame <selector|@ref|--name name|--url pattern|main>');\n\n      if (target === 'main') {\n        bm.setFrame(null);\n        bm.clearRefs();\n        return 'Switched to main frame';\n      }\n\n      const page = bm.getPage();\n      let frame: Frame | null = null;\n\n      if (target === '--name') {\n        if (!args[1]) throw new Error('Usage: frame --name <name>');\n        frame = page.frame({ name: args[1] });\n      } else if (target === '--url') {\n        if (!args[1]) throw new Error('Usage: frame --url <pattern>');\n        frame = page.frame({ url: new RegExp(escapeRegExp(args[1])) });\n      } else {\n        // CSS selector or @ref for the iframe element\n        const resolved = await bm.resolveRef(target);\n        const locator = 'locator' in resolved ? resolved.locator : page.locator(resolved.selector);\n        const elementHandle = await locator.elementHandle({ timeout: 5000 });\n        frame = await elementHandle?.contentFrame() ?? null;\n        await elementHandle?.dispose();\n      }\n\n      if (!frame) throw new Error(`Frame not found: ${target}`);\n      bm.setFrame(frame);\n      bm.clearRefs();\n      return `Switched to frame: ${frame.url()}`;\n    }\n\n    // ─── UX Audit ─────────────────────────────────────\n    case 'ux-audit': {","sourceCodeStart":1000,"sourceCodeEnd":1036,"githubUrl":"https://github.com/garrytan/gstack/blob/94993f74012782fd94416dd44b8314f6363a13a4/browse/src/meta-commands.ts#L1000-L1036","documentation":"When `frame` is called with `--url`, the command expects a pattern string, escapes it with `escapeRegExp`, compiles a `RegExp`, and calls `page.frame({ url: ... })` (lines 1017-1018). If the pattern is missing the regex cannot be built.","triggerScenarios":"`browse frame --url` with no following token.","commonSituations":"Truncated command, or the URL pattern was a shell variable that expanded to empty.","solutions":["Provide a pattern: `browse frame --url 'cdn\\.example\\.com/player'`.","The pattern is regex-escaped, so literal dots/slashes are fine — no need to double-escape.","If matching by name is easier, switch to `--name`."],"exampleFix":"// before\nbrowse frame --url\n// after\nbrowse frame --url 'embed\\.example\\.com'","handlingStrategy":"validation","validationCode":"if (args[0] === '--url' && !args[1]) {\n  throw new Error('frame --url requires a URL pattern argument');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pair `--url` with its pattern at the call site.","Guard against empty shell-variable expansion before dispatch."],"tags":["frame","argument-parsing","usage"],"backgroundTag":null,"analyzedSha":"94993f74012782fd94416dd44b8314f6363a13a4","analyzedAt":"2026-08-12T04:06:23.140Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}