{"record":{"id":"63500aa54c3f72b3","repo":"garrytan/gstack","slug":"usage-frame-selector-ref-name-name-url-patt","errorCode":null,"errorMessage":"Usage: frame <selector|@ref|--name name|--url pattern|main>","messagePattern":"Usage: frame <selector\\|@ref\\|--name name\\|--url pattern\\|main>","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"browse/src/meta-commands.ts","lineNumber":1003,"sourceCode":"        // checks, or forge tab ownership for cross-agent authorization bypass.\n        await bm.restoreState({\n          cookies: validatedCookies,\n          pages: data.pages.map((p: any) => ({\n            url: typeof p.url === 'string' ? p.url : '',\n            isActive: Boolean(p.isActive),\n            storage: null,\n          })),\n        });\n        return `State loaded: ${data.cookies.length} cookies, ${data.pages.length} pages`;\n      }\n\n      throw new Error('Usage: state save|load <name>');\n    }\n\n    // ─── 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","sourceCodeStart":985,"sourceCodeEnd":1021,"githubUrl":"https://github.com/garrytan/gstack/blob/94993f74012782fd94416dd44b8314f6363a13a4/browse/src/meta-commands.ts#L985-L1021","documentation":"The `frame` meta-command requires a target argument selecting which frame to switch to (line 1003): a CSS selector, an `@ref`, `--name <name>`, `--url <pattern>`, or the literal `main`. With no target the command cannot decide which frame to enter, so it throws this usage error.","triggerScenarios":"`browse frame` with no arguments.","commonSituations":"Forgetting to pass the iframe selector; an agent constructing the call lazily; expecting the command to auto-pick the only frame.","solutions":["Switch to main: `browse frame main`.","By name: `browse frame --name <frameName>`.","By URL pattern: `browse frame --url 'example\\.com/embed'`.","By element: `browse frame iframe#widget` or `browse frame @e5`."],"exampleFix":"// before\nbrowse frame\n// after\nbrowse frame main","handlingStrategy":"validation","validationCode":"if (!args[0]) {\n  throw new Error('frame requires a target: <selector|@ref|--name n|--url pattern|main>');\n}","typeGuard":"const isFrameTarget = (s: string): boolean =>\n  s === 'main' || s === '--name' || s === '--url' ||\n  /^(?:@e|@c|\\.|#|\\[)/.test(s);","tryCatchPattern":null,"preventionTips":["Always pass an explicit target; don't rely on a default.","Use `frame main` as the safe reset when in doubt."],"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"}