Coverage decisions: fossilize 80 V3 JS API surface decisions#274
Merged
Conversation
Deploying fliplet-cli with
|
| Latest commit: |
172d42a
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://e188dbe2.fliplet-cli.pages.dev |
| Branch Preview URL: | https://v3-coverage-decisions.fliplet-cli.pages.dev |
tonytlwu
force-pushed
the
v3/coverage-decisions
branch
from
a9da075 to
37c3da1
Compare
Commits the 80-row coverage decisions table from the multi-pass audit (7 parallel subagents read every JS file across 46 fliplet-* packages in ~/Sites/fliplet/api/public/assets/) so the same review work doesn't happen again in 6 months. `docs/v3/coverage-decisions.md` (new): - Decision tallies: 30 to-be-documented + 1 effectively-documented + 3 partial + 42 excluded + 4 Studio-only = 80 surfaces. - Per-row rationale grouped by V3-relevance: documented surfaces, the excluded set (with reason: V1-only, Studio-only, internal, etc.), and Studio-only surfaces that are V3-relevant but not for app authors / AI. - Explicit acceptance of cross-repo drift: there is no automated mechanism that catches a new fliplet-* package landing in fliplet/api (rejected as over-investment given 1-2 packages/year cadence). The trade-off is documented in the doc so the next maintainer sees it was deliberate. - "Audit method (lessons captured)" section captures the three audit correction rounds: suspected-gaps-only audits miss surfaces; per- package walks are required (not just fliplet-core); greps miss window.X assignments and nested directories. Pointer to the source-of-truth spreadsheet so future maintainers know where to add new surfaces before mirroring decisions back into this doc. Verification: - node bin/build-agent-indexes.mjs --strict → exit 0 - npm run test:unit → 127/127 pass Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Working planning artifacts (e.g. the fliplet-native scope review delivered for sign-off) don't belong in the published doc index. plans/ joins the existing _templates/, _includes/, etc. in EXCLUDED_DIRS. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Planning artifact delivered for sign-off before Phase B authoring. Surveys 13 sub-modules in fliplet-native (source-size + last-touched + public-method enumeration + V3-relevance + recommendation). Outcomes (all approved): - 9 sub-modules document fully: Native (top), AppManagement, Interaction, Updates, Downloads, Locale, Maintenance, Notifications, StatusBar - 4 keep but skip docs: Data (telemetry queue, dormant since 2022), Authentication (NativeStorage wrapper superseded by Fliplet.User), Config (legacy FV environment switcher), Templates (internal template strings for the Updates UI) - 0 delete from source — all dormant modules are still referenced in the boot sequence File-grouping recommendation (approved): hybrid (b) — main file docs/API/fliplet-native.md covers 7 sub-namespaces consolidated, plus docs/API/fliplet-native/downloads.md (56KB / 25+ methods) and docs/API/fliplet-native/maintenance.md (47KB / 22+ methods) get their own files. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ytics-spa, error-tracking, router relocation, require namespace Lands 5 new package docs and 1 new core namespace doc for surfaces the May 2026 capabilities audit identified as missing. New docs (5): - fliplet-runtime.md — V3 SPA bootstrap; documents the callable Fliplet(callback) shim, Fliplet.extend, Fliplet.parseNumber, Fliplet.initializeLocale, the boot sequence (web auto-init vs native manual), and links out to the 4 ambient namespaces it registers (Env, Registry, Studio, Navigator) plus Locale. category: framework. - fliplet-service-worker.md — push notification + click handler. Documents both event listeners (push, notificationclick), the mark-as-read POST behavior, the action==='screen' bypass, registration from fliplet-core (Modernizr.pushnotification gated, not in preview), and the URL-query-param channel that's the only SW→app communication. category: framework. - fliplet-analytics-spa.md — auto pageView tracker. Documents the install guard, History API monkey-patch, route resolution against the v3.routes manifest, the 5-field event payload (_pageTitle, _route, _routeRaw, _routeParams, _routeName), and the dedup logic. category: analytics. - fliplet-error-tracking.md — observability runtime. Documents the 3 hooks (onerror, unhandledrejection, Promise.prototype.then wrap that catches Vue-silenced errors), buffering policy (BUFFER_MAX=50, SESSION_MAX=500, FLUSH_MS=5000), the sendBeacon page-unload path, and the Fliplet.App.Logs.createBatch sink. category: observability (the first entry in the new bucket). - core/require.md — Fliplet.require + lazy/list/get/chain family. Documents the two-tier model (bootstrap gate vs on-demand loader), the 3 input modes of .lazy (numeric media file ID, registered name, raw URL), and the chainPromises memoization in .chain. category: framework. Relocation: - fliplet-router.md moved from API/v3/ to API/ so it enters the V3 library catalog (catalog path regex is ^API/fliplet-[^/]+\.md$). New frontmatter adds category: navigation, capabilities[], and a notes field flagging the boot-time dependency on fliplet-core + fliplet-media. - Source-discrepancy fix in the same move: the existing doc listed a 'no-session' reason code that router.js does NOT implement (deliberately removed at lines 113-120 per source comment — passport-less visitors still have a session object, so the presence check let protected screens through). Reason codes table collapses to 'unknown-route' and 'media-denied'; corresponding text in the denial-shape description removed. - Inbound link updates in API/v3/routing.md and API/v3/app-bootstrap.md. - coverage-decisions.md row 4 updated to reflect new canonical path. V3 catalog now contains 45 libraries (up from 39). docs/v3/capabilities.md regenerates with sections populated for framework, navigation, and observability. Verification: node bin/build-agent-indexes.mjs --strict → exit 0. npm run test:unit → 127/127 pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Fills in 12+ sub-namespaces the May 2026 capabilities audit flagged as missing or partial. Each extension mirrors the existing parent doc's style and is verified against fliplet-core/1.0/core.js (or the package's source).
core/organizations.md (+1 H2):
- Fliplet.Organizations.Analytics — POST v1/organizations/:orgId/analytics. Wrapper passes data verbatim; accepted shape determined by REST endpoint. Mirrors the existing Audit logs section.
core/app.md (+3 H2 + 4 in-place additions):
- New: ## Releases (Fliplet.App.Releases.get → delegates to Fliplet.App.get + extracts releases; cached)
- New: ## Analytics — full Fliplet.App.Analytics surface: track / event / pageView / get / count + Aggregate.{get,count} + Session.{init,reset} + enable/disable/isUserTracking. Documents side effects: triggers App.Actions + App.V3.Actions on send; offline queue in flAnalyticsQueue; skip conditions (taskToken, isTrackingEnabled=false).
- New: ## Push notification subscriptions (Fliplet.App.Subscriptions.get → device push registrations)
- Extended ## Locales with getDefault()
- Extended ## Logs with createBatch({logs, async})
- Extended ## Settings with formal signatures table + development-mode caveat (set/unset short-circuit and mutate window.ENV.appSettings directly when Fliplet.Env.get('development') is true)
- Extended ## Device orientation with the 640px portrait-forcing breakpoint and the lock('all') → unlock() delegation
fliplet-media.md (+4 H3 under existing ## Files):
- get(id), getAll({files, attributes?}), getContents(id, {size, format, quality, responseType}), getCachedImages({folderId, files, size, format, quality, onProgress}). Documents Cache TTLs (folder list 10 min on native; getAll 1 hour) and the web-vs-native getCachedImages divergence (signed URLs on web, downloaded via Fliplet.Native.Downloads on native).
fliplet-datasources.md (+1 H2 ## Offline database):
- Fliplet.DataSources.Database — constructor + dataSource() + 8 collection methods (find/findById/insert/remove/update/applyDiff/indexes/index). Highlights: module-level bundle cache, deep-merge semantics of update(), fullRefresh behavior of applyDiff. Marked native-only with web fallback for dev/test.
Verification: node bin/build-agent-indexes.mjs --strict → exit 0. npm run test:unit → 127/127 pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reflects the 6 new V3-catalog entries (fliplet-runtime, fliplet-service-worker, fliplet-analytics-spa, fliplet-error-tracking, fliplet-router, core/require) and the section-population on /v3/capabilities for framework, navigation, and observability buckets. V3 catalog grows from 39 to 45 libraries. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…nce sub-docs (Phase B)
Lands the approved hybrid layout from Phase A: one consolidated main doc covering 7 sub-namespaces inline, plus two separate sub-docs for the largest sub-modules.
docs/API/fliplet-native.md (main, in V3 catalog):
- category: native, capabilities[] tagged for app management / native bridge / status bar / etc.
- Prominent native-wrapper-only callout + Fliplet.Env.get('platform') feature-detect pattern in the first example.
- 7 sub-namespaces covered as H2 sections:
- Fliplet.Native (bootstrap: init, getFrameworkVersion)
- Fliplet.Native.AppManagement (14 public methods covering local-app registry, server sync, asset diffing, icon resolution)
- Fliplet.Native.Interaction (tap-and-hold + top-swipe to return to Fliplet Viewer bookshelf). Note: namespace is .Interaction, NOT .AppInteraction (corrected from earlier audit).
- Fliplet.Native.Updates (init, checkForUpdates, createUpdateTimer — 3 public methods. Updates types SILENT/VISIBLE/FORCED. Hooks: checkForUpdates, updateCompleted, updateFailed, dataSourceUpdated.)
- Fliplet.Native.Locale (init(appId), updateSessionLocale; bridges to Fliplet.initializeLocale())
- Fliplet.Native.Notifications (clarified: notification CLICK handler, NOT push sender. Push send is Fliplet.App.PushNotifications.send.)
- Fliplet.Native.StatusBar (iOS-only init, but setColor/show/hide/isVisible work on both. bright() W3C brightness check. notch property.)
docs/API/fliplet-native/downloads.md (sub-doc, NOT in catalog):
- 15 public methods covering app-bundle download orchestration. Documents concurrency caps (8 iOS/Win, 5 Android), retry policy (4 attempts for timeout/network/SSL), non-severe error classification (missing images / entries.json don't fail update), DOWNLOAD_CANCEL sentinel, getPercentageDownload return-value semantics (100 for installed, -1 for unknown). Hooks: updateCompleted, updateFailed. Excluded from catalog (exclude_from_v3_catalog: true) — covered by parent Fliplet.Native entry.
docs/API/fliplet-native/maintenance.md (sub-doc, NOT in catalog):
- 27 public methods (more than the original scope estimate of ~22 — found additional Launch helpers and App-list helpers in the IIFE return block). Covers the full file-system abstraction: read/write/copy/move/remove/directory ops/existence checks plus unzip and the launch-time helpers. Documents the writeFile { create: false } + required mimeType gotcha. Excluded deprecated methods (getAppConfigurationFile, getApplicationMode, startBundleCopyProcess).
V3 catalog grows from 45 to 46 libraries (fliplet-native main doc only — sub-docs intentionally excluded). docs/v3/capabilities.md regenerates with fliplet-native listed under Native category.
Verification:
- node bin/build-agent-indexes.mjs --strict → exit 0
- npm run test:unit → 127/127 pass
- 105 fliplet-js-api docs indexed (up from 102)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Jekyll layout at _layouts/default.html:351 prints {{ page.title }} as literal text in the .project-name div above the body H1. When frontmatter has `title: "`Fliplet.X`"`, the header div renders with visible backticks instead of the intended <code> formatting.
Scope: 6 affected docs across the repo (2 pre-existing, 4 added in this branch):
- API/core/storage.md (pre-existing)
- API/core/screens.md (pre-existing)
- API/core/require.md
- API/fliplet-native.md
- API/fliplet-native/downloads.md
- API/fliplet-native/maintenance.md
Fix: strip backticks from `title:` in all 6. Body H1 keeps the backticks for inline-code formatting via markdown.
Regression prevention (validateFrontmatter):
- New lint: errors if title contains a backtick, with a hint pointing to the body H1
- Tests: 2 new cases (flags backticks; accepts plain text titles)
- CONTRIBUTING.md: explicit guidance under step 2 of the new-package-doc checklist
Verification:
- Injected violation: backtick title on fliplet-runtime → strict catches with hint
- Clean state: --strict exit 0, 46 V3 catalog libraries unchanged
- npm run test:unit: 129/129 pass (was 127; +2 new tests)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
tonytlwu
force-pushed
the
v3/coverage-decisions
branch
from
e5e3752 to
172d42a
Compare
tonytlwu
changed the base branch from
v3/capabilities-audit-foundations
to
master
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
1 participant
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.
Summary
Commits the per-row coverage decisions from the May 2026 capabilities audit so the same review work doesn't have to happen again in 6 months.
Stacks on #267 (foundations PR). The new doc uses the
categoryschema + lints from that PR. If #267 lands first, this rebases cleanly onto master.Tallies (80 rows total):
fliplet-runtime(its surfaces Env/Registry/Studio/Navigator are incore/*)fliplet-native, V1fliplet-pages, top-levelFliplet.Native(covered by per-sub-module rows)The doc captures three things you'd otherwise re-derive in 6 months
Fliplet.App.Subscriptionsis to-be-documented (push device subs, not paid subs) andFliplet.Communicate.AESisn't.Fliplet/apiandfliplet-cli/docs— rejected as over-investment given 1-2 packages/year. Documented so the next maintainer sees it was a deliberate choice, not an oversight.fliplet-core, greps misswindow.Xand nested dirs). Future audits should walk every JS file via subagents.Source of truth
Living spreadsheet linked at the end of the doc: https://docs.google.com/spreadsheets/d/1IoYblMJfekfKRSYf8Q19ohu40jlN_vDpJyFyd7xD4u8/edit
When a new surface appears, add a row there with V3-relevance + rationale, then mirror into this doc.
Test plan
node bin/build-agent-indexes.mjs --strict→ exit 0npm run test:unit→ 127/127 pass🤖 Generated with Claude Code