DEV-1264: Barcode dev docs — add attachScanner() (web + native)#281
Open
farhantariq12b wants to merge 8 commits into
Open
DEV-1264: Barcode dev docs — add attachScanner() (web + native)#281farhantariq12b wants to merge 8 commits into
farhantariq12b wants to merge 8 commits into
Conversation
… wording Recommend Fliplet.Barcode.attachScanner() — the low-level, UI-less scanner you wrap in your own UI (works on web and native) — and drop internal jargon (no fliplet-pages / overlay / V2 / V3) so the wording is behavioral for devs and the AI. scan()/encode()/show() unchanged. Rebuild .well-known indexes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Deploying fliplet-cli with
|
| Latest commit: |
f091bae
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://b995030d.fliplet-cli.pages.dev |
| Branch Preview URL: | https://feat-dev-1264-barcode.fliplet-cli.pages.dev |
…hortcut Local E2E (build 893) confirmed the V3 AI builder fetches this doc (via the docs-origin override → CF preview) but still generated Fliplet.Barcode.scan(). Root cause: scan() was documented first with a complete usage example, so the model picked it before reaching the "(recommended)" attachScanner() section. Fix is ordering + directive framing, not delivery: - attachScanner() now appears first, explicitly "the method to reach for when you build the scanning screen yourself" (works the same web + native). - scan() moved below, framed as a convenience shortcut that points back to attachScanner() for app screens. - intro leads with attachScanner() and a "tap a button to scan" example note. No internal jargon (no V2/V3/Overlay) — behavioral wording only. Co-Authored-By: Claude <noreply@anthropic.com>
Resolve conflicts in generated docs/.well-known/* by regenerating from source (node bin/build-agent-indexes.mjs) after the merge. docs/API/fliplet-barcode.md auto-merged: keeps the attachScanner-first content and master's `category: media` frontmatter. No hand-editing of generated index files. Co-Authored-By: Claude <noreply@anthropic.com>
…rence - Add docs/API/v3/barcode.md — a V3 scanning guide leading with attachScanner() (embedded, web + native), authored to the V3 guide conventions (mirrors auth.md / routing.md). - De-editorialize docs/API/fliplet-barcode.md back to a neutral factual API reference; link out to the V3 guide instead of steering readers. - Regenerate .well-known indexes (llms.txt now lists the V3 guide). Co-Authored-By: Claude <noreply@anthropic.com>
scan() is native-only and is the wrong method for V3's web+native target. The builder now reads this guide as its sole barcode source, and it latches onto any runnable method in context, so even a "don't use scan()" mention is a risk. Removed every scan() reference; scan() stays documented in the shared Fliplet.Barcode API reference for non-V3 use. Co-Authored-By: Claude <noreply@anthropic.com>
tonytlwu
requested changes
Jun 15, 2026
tonytlwu
left a comment
tonytlwu
left a comment
Contributor
There was a problem hiding this comment.
Look at each of my rejection comments carefully. How are you going to ensure AI doesn't make this mistake again?
Addresses review on #281 — the catalog/capabilities/registry pointed at the shared (non-V3) barcode doc, and the V3 redirect lived as a Studio-side override. Now it's derived from frontmatter, so the wrong version can't be hand-set. - API/fliplet-barcode.md → v3_relevant: false + exclude_from_v3_catalog: true (legacy/non-V3 reference; same pattern as app-actions v1/v2). - API/v3/barcode.md declares package/namespace/category/capabilities → it is now the V3 catalog entry. docUrl, the capabilities index and Studio's registry all derive its URL automatically (no hand-set URLs, no Studio override). - emitter: an API/v3/*.md doc becomes a catalog entry when it declares `package:` (the gate keeps pattern guides — routing/auth/frameworks — out); add a `namespace:` override so a guide-titled doc still advertises the real JS global. - lint: validateCatalogUniqueness (--strict) fails the build if a package resolves to >1 catalog doc — tripwire against a forgotten opt-out. - docs/CLAUDE.md: document the dedicated-V3-doc pattern + "primitive-only" rule. - Regenerated .well-known indexes; unit tests 163/163. Co-Authored-By: Claude <noreply@anthropic.com>
tonytlwu
requested changes
Jun 17, 2026
…), drop v2 links) Tony's review: v3/barcode.md is the sole V3 catalog entry for fliplet-barcode (v2 fliplet-barcode.md is excluded from V3), so it must be COMPLETE — it can't lean on the v2 reference for the generation methods, and it must not link the builder back to the v2 doc (which still contains the native-only scan()). - Document Fliplet.Barcode.show() and encode() inline with full signatures and options (both work web + native; QR + barcode formats, color, sizing). - Broaden title/H1/intro to "V3 barcodes" — the doc now covers scan + generate. - Remove all three outbound links to ../fliplet-barcode.md (Prerequisites, Generating barcodes, Related) so the exclusion isn't defeated by cross-links. - scan() stays out entirely (native-only). - Regenerate derived artifacts (llms*, v3 catalog, capabilities, skills index). Co-Authored-By: Claude <noreply@anthropic.com>
show() renders the barcode via Fliplet.UI.Toast, and Fliplet.UI is exclude_from_v3_catalog (the V3 design system replaces it — the builder is never told it exists). Documenting show() would steer the AI into a namespace V3 deliberately hides, the same contradiction as linking back to the v2 doc. encode() is the clean V3 generation primitive: pure, returns Base64, no UI dependencies — the builder places the image in its own UI (the same "you own the UI" model attachScanner() teaches). show() : encode() :: scan() : attachScanner() — keep the primitive, drop the UI-owning convenience. - Remove the show() section and all show() mentions (intro, prerequisites, description); keep encode() as the sole generation method. - Regenerate derived artifacts (llms*, v3 catalog, capabilities, skills index). Co-Authored-By: Claude <noreply@anthropic.com>
farhantariq12b
force-pushed
the
feat/DEV-1264-barcode
branch
from
3210199 to
f091bae
Compare
tonytlwu
approved these changes
Jun 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
JIRA
https://weboo.atlassian.net/browse/DEV-1264
Summary
Adds a V3-only barcode scanning doc and makes it the catalog entry the V3 AI builder reads — frontmatter-driven, so the builder always resolves barcode to the cross-platform primitive.
API/v3/barcode.md— a V3 scanning guide that leads with, and contains only,Fliplet.Barcode.attachScanner()(UI-less, embed-in-your-own-UI, web + native). Authored to the write-dev-doc conventions; mirrors theAPI/v3/auth.md/routing.mdpattern.API/fliplet-barcode.mdstays as the neutral, factual legacy/non-V3 reference (attachScanner/scan/show/encode), nowv3_relevant: false+exclude_from_v3_catalog: true. Human/V2 readers unaffected; V3-builder steering lives only in the V3 doc.package/namespace/category/capabilities, so the catalog (llms-v3-libraries.json), the capabilities index, and Studio's registry all derive its URL automatically — barcode →…/API/v3/barcode.md, namespaceFliplet.Barcode.This is the litmus test for the native-capability system: one UI-less cross-platform JS API + a behavioral V3 doc, delivered through the existing pipeline.
Review feedback addressed (Tony, 2026-06-15)
API/v3/barcode.md; shared ref opts out.v3_relevantneeds to befalse" (shared doc) → set, plusexclude_from_v3_catalog: true(same pattern as app-actions v1/v2).scan()→ the V3 doc has zeroscan()references;scan()stays in the legacy reference. The builder reads the V3 doc as its sole source, so it can't pick a method it never sees.Future-proofing (so this can't regress)
API/v3/*.mddoc withpackage:becomes the catalog entry (the gate keeps pattern guides — routing/auth/frameworks — out); anamespace:override lets a guide-titled doc advertise the real JS global. No hand-set URLs anywhere.validateCatalogUniqueness(--strict) fails the build if a package resolves to >1 catalog doc — a forgotten opt-out can't ship silently.docs/CLAUDE.md, so the next native capability follows the same rails.Test plan
FLIPLET_DOCS_HOSTto this PR's CF Pages preview, build a barcode app in the V3 AI builder → generatedScanner.jsusesattachScanner()with 0scan()calls (verified E2E).Pairs with
Fliplet.Barcode.attachScanner()) · studio #8634 (docs-preview origin + preview permissions)🤖 Generated with Claude Code