SPOT-002: shared/spot.js — hunk-substrate locators (#L123, #needle, #/re/, #'pattern')

Now: OPEN

Input

Context

Every view (why:, cat:, diff:, spot:) emits the same {uri, text, toks} hunk stream, so the locator/search layer must consume tokenized hunks, not raw bytes. Hidden link toks — U (click-target URI bytes) and O (why's origin-commit link) — are zero-width and must be invisible to matching AND to line/col math. Supersedes SPOT-001 (grammar re-ruled by gritzko 2026-07-18).

Consumers: why:/cat:/diff: fragment scoping, the spot view rebuild, the pager's in-view /jump — all funnel into one resolver.
Any emitted hunk is valid input: a why/diff hunk is searchable without re-tokenizing.

Goals

shared/spot.js: parse a fragment locator, resolve it over one or many hunks, clip sub-hunks. Fragment grammar (ruling, 2026-07-18):

#L123, #L123-160 — line / line range (the C HUNKu8sMakeURI #L42 convention);
#needle — substring (CAPOGrep twin, the fallback);
#/re/ — regex (CAPOPcreGrep twin);
#'tok pattern' — structural SPOT (a-z bind one token, A-Z a block, two-space gap).

Constraints

Hashlets resolve via resolve_hash FIRST; spot.js never sees them. L-prefixed lines keep the namespaces disjoint; a bare hex-looking needle loses to the hashlet.
Reuse: lift views/spot/match.js matchers; needle tokenizing rides tok.parse — no manual parsing beyond the locator grammar.
Spans are hunk-byte-space truth; line/col derived in the same walk, U/O toks excluded from both.

WIP

Design decisions

API sketch (C twins: SPOTTokenize, SPOTInit/SPOTNext, SPOTReplace, CAPOGrep/CAPOPcreGrep, HUNKu32sClip, grepCtx):

parse(frag) → typed locator (line | substr | regex | spot).
compile(loc, ext) — per-syntax needle prep; tokenizes 'pattern' with the hunk's own lexer, so one locator works across .c/.js/.mkd hunks; m.next(hunk) → {lo, hi, line, col} | null, SPOTNext-style.
find(loc, hunk) — one hunk: compile against hunk.ext, drain next() → all spans ascending; callers pick first/nearest/all.
scan(loc, hunks) — many hunks: lazy, yields {hunk, spans}, recompiles only on ext change (mixed-language result sets).
clip(hunk, lo, hi) — HUNKu32sClip twin: token-edge snap, a hidden U/O sticks to its visible predecessor (never split a [visible][U/O] pair); line numbers stay absolute (pre-clip).
window(loc, hunk, nctx) — find + merge ±nctx line windows (grepCtx) + clip → subhunk — the one-call view helper.
fromFile(bytes, ext) — tok.parse wrapper for raw-file callers; views pass hunks as-is.
replace(loc, hunk, tmpl) — SPOTReplace twin, structural locators only.

TODOs

parse + compile + find over hunks; four locator syntaxes
U/O skip in matchers and line/col accounting (shared walk)
clip + window, U/O-pair-safe, absolute gutter lines
scan over multi-hunk streams, per-ext recompile
lift match.js matchers to shared (no behavior change) — views/spot/{match,ext}.js → shared/, search.js repointed
repro: golden table — each syntax over .c/.js/.mkd fixtures, why-hunk input leg (O toks present), hashlet NON-capture leg

Blockers and bummers

replace ships literal-span only: true SPOTReplace bind back-substitution needs shared/match.js to expose its a-z/A-Z binds (today spans only) — follow-up ticket candidate.

Outcome

Staged (put only, NOT posted) in //SPOT-002 on base //SPOT/#9928a0be: shared/{spot,match,ext}.js new + views/spot/search.js repointed; test sub: test/spot/locator/{check.js,run.sh}. The two relocated originals are pending DELETIONS (x) — put can't stage removals, the commit must capture them.
Orchestrator re-verified 2026-07-19: be-js-spot-locator PASS, be-js-spot-search regression PASS (own re-run, not just the worker's word).
Suggested commit: SPOT-002: shared/spot.js hunk locators + lift matchers