@dasasian/firebase-structured-logger 1.2.0 → 1.3.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dasasian/firebase-structured-logger",
-  "version": "1.2.0",
+  "version": "1.3.0-rc.1",
   "description": "Structured logging for Firebase and Google Cloud web apps — browser, backend, and tools",
   "license": "MIT",
   "author": "Dasasian",
@@ -38,10 +38,22 @@
       "types": "./dist/client/navigation.d.ts",
       "default": "./dist/client/navigation.js"
     },
+    "./client/navigation/vue-router": {
+      "types": "./dist/client/navigation/vue-router.d.ts",
+      "default": "./dist/client/navigation/vue-router.js"
+    },
+    "./client/navigation/react-router": {
+      "types": "./dist/client/navigation/react-router.d.ts",
+      "default": "./dist/client/navigation/react-router.js"
+    },
     "./client/timing": {
       "types": "./dist/client/timing.d.ts",
       "default": "./dist/client/timing.js"
     },
+    "./client/views": {
+      "types": "./dist/client/views.d.ts",
+      "default": "./dist/client/views.js"
+    },
     "./functions": {
       "types": "./dist/functions/index.d.ts",
       "default": "./dist/functions/index.js"
@@ -59,9 +71,18 @@
       "client/navigation": [
         "dist/client/navigation.d.ts"
       ],
+      "client/navigation/vue-router": [
+        "dist/client/navigation/vue-router.d.ts"
+      ],
+      "client/navigation/react-router": [
+        "dist/client/navigation/react-router.d.ts"
+      ],
       "client/timing": [
         "dist/client/timing.d.ts"
       ],
+      "client/views": [
+        "dist/client/views.d.ts"
+      ],
       "functions": [
         "dist/functions/index.d.ts"
       ],
@@ -82,7 +103,7 @@
     "build:watch": "tsc --watch",
     "clean": "rm -rf dist",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.check.json",
-    "test": "tsx tests/logger.ts && tsx tests/browserBundle.ts && tsx tests/breadcrumbs.ts && tsx tests/navigation.ts && tsx tests/timing.ts && tsx tests/rateLimiter.ts && tsx tests/errorHandler.ts && tsx tests/attachments.ts && tsx tests/feedback.ts && tsx tests/paths.ts && tsx tests/loadsWithoutOptionalPeers.ts && tsx tests/sourceMapStripping.ts && FUNCTIONS_EMULATOR=true tsx tests/errorPayload.ts && FUNCTIONS_EMULATOR=true tsx tests/requestLogger.ts && FUNCTIONS_EMULATOR=true tsx tests/serverTrace.ts && FUNCTIONS_EMULATOR=true tsx tests/handler.ts && FUNCTIONS_EMULATOR=true tsx tests/httpHandler.ts && FUNCTIONS_EMULATOR=true tsx tests/symbolication.ts && FUNCTIONS_EMULATOR=true tsx tests/publicApi.ts && FUNCTIONS_EMULATOR=true tsx tests/configureTwice.ts && FUNCTIONS_EMULATOR=true tsx tests/deprecatedNames.ts && tsx tests/productionOutput.ts && tsx tests/storageChain.ts && tsx tests/entrySize.ts && tsx tests/handlerSymbolication.ts && tsx tests/releaseResolution.ts && tsx tests/sourceMapCacheBounds.ts && tsx tests/doctor.ts && tsx tests/doctorProcess.ts && tsx tests/uploadSourcemapsBackend.ts",
+    "test": "tsx tests/logger.ts && tsx tests/browserBundle.ts && tsx tests/breadcrumbs.ts && tsx tests/navigation.ts && tsx tests/vueRouterNavigation.ts && tsx tests/reactRouterNavigation.ts && tsx tests/timing.ts && tsx tests/rateLimiter.ts && tsx tests/errorHandler.ts && tsx tests/attachments.ts && tsx tests/feedback.ts && tsx tests/paths.ts && tsx tests/loadsWithoutOptionalPeers.ts && tsx tests/sourceMapStripping.ts && FUNCTIONS_EMULATOR=true tsx tests/errorPayload.ts && FUNCTIONS_EMULATOR=true tsx tests/requestLogger.ts && FUNCTIONS_EMULATOR=true tsx tests/serverTrace.ts && FUNCTIONS_EMULATOR=true tsx tests/handler.ts && FUNCTIONS_EMULATOR=true tsx tests/views.ts && FUNCTIONS_EMULATOR=true tsx tests/httpHandler.ts && FUNCTIONS_EMULATOR=true tsx tests/symbolication.ts && FUNCTIONS_EMULATOR=true tsx tests/publicApi.ts && FUNCTIONS_EMULATOR=true tsx tests/configureTwice.ts && FUNCTIONS_EMULATOR=true tsx tests/deprecatedNames.ts && tsx tests/productionOutput.ts && tsx tests/storageChain.ts && tsx tests/entrySize.ts && tsx tests/handlerSymbolication.ts && tsx tests/releaseResolution.ts && tsx tests/sourceMapCacheBounds.ts && tsx tests/doctor.ts && tsx tests/doctorProcess.ts && tsx tests/uploadSourcemapsBackend.ts",
     "prepublishOnly": "npm run clean && npm run build",
     "smoke:deploy": "cd smoke/functions && npm install && npm run build && cd .. && firebase deploy --only functions --project $(grep '^FSL_SMOKE_PROJECT=' .env.local | cut -d= -f2)",
     "smoke:deploy:run": "bash smoke/cloudrun/deploy.sh",
@@ -119,8 +140,14 @@
     "firebase-admin": "^14.5.0",
     "firebase-functions": "^7.4.0",
     "jsdom": "^30.1.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "react-router-6": "npm:react-router@^6.30",
+    "react-router-7": "npm:react-router@^7.18",
     "tsx": "^4.23.15",
-    "typescript": "~6.0.3"
+    "typescript": "~6.0.3",
+    "vue": "^3.5.43",
+    "vue-router": "^4.6.4"
   },
   "engines": {
     "node": ">=22"

package/skills/logs/SKILL.md

@@ -58,23 +58,23 @@ Using the Explore agent's output, check the target file against the rules below.
 Breadcrumbs reconstruct what the user was doing before an error — a session timeline, not just a wrapper around service calls. They belong primarily in components and screens, not service files.
 
 UX-layer breadcrumbs to check for (flag if missing):
-- Screen/route changes → `bc.nav('ScreenName')`
-- Modal open/close → `bc.action('open_item_modal', { itemId })`
-- Tab switches → `bc.action('switch_tab', { tab })`
+- Page changes → `enableNavigation()` once at startup (or `navigatedTo('ScreenName')` when the URL does not change). Flag hand-written `bc.nav` / `setScreen` — deprecated, and ignored once navigation is on
+- Opening a modal or switching a tab → `bc.action('open_item_modal', { itemId })`, `bc.action('switch_tab', { tab })` — the step the user took
+- Dialogs, tabs and steps that matter → `data-fsl-view="Name"` on their root element, with `enableViews()` once at startup. Flag a name built from a value (`order-${id}`) and a mark on list items
 - Explicit user decisions → `bc.action('merge_chosen')`, `bc.action('discard_changes')`
 - Scan/camera events → `bc.action('barcode_scanned', { barcode })`
 
 Service-layer breadcrumbs (secondary — useful but not sufficient on their own):
 - Before a Firestore/API call → `bc.action('save_item', { itemId })`
-- On error → `bc.error('save_failed', { itemId })`
+- An error the code handled and did not log (a retry that worked) → `bc.handledError('save_failed', { itemId })`. An error that is logged needs no breadcrumb — flag `bc.handledError` next to a `logger.error` for the same failure as redundant
 
 **A component file with no UX-layer breadcrumbs is almost certainly missing them. A service file with only service-layer breadcrumbs may be fine.**
 
 API:
 - `bc.action(name: string, data?)` — user-initiated operations and decisions
 - `bc.state(name: string, data?)` — significant state changes
-- `bc.nav(screen: string)` — screen/route changes
-- `bc.error(type: string, data?)` — when an error occurs
+- `bc.handledError(type: string, data?)` — an error handled and not logged (`bc.error` is its deprecated old name)
+- Page changes are not a `bc.*` call — see navigation below
 
 **Label completeness**
 - For each function, check which `AppLabels` fields are in scope as variables
@@ -166,18 +166,26 @@ Import `bc` from `firebase-structured-logger/client`:
 ```ts
 bc.action(name: string, data?: Record<string, unknown>): void  // before operations
 bc.state(name: string, data?: Record<string, unknown>): void   // on state changes
-bc.nav(screen: string): void                                   // on navigation
-bc.error(type: string, data?: Record<string, unknown>): void   // on errors
+bc.handledError(type: string, data?: Record<string, unknown>): void   // an error handled, not logged
 ```
+`bc.nav` and `bc.error` are deprecated in 1.3 and removed in 2.0 — flag them.
 
 Import `enableNavigation` from `firebase-structured-logger/client/navigation`:
 ```ts
-enableNavigation(options?: { routeFor?: (path: string) => string | undefined; cleanPath?: (path: string) => string; path?: false }): void
+enableNavigation(options?: { labelsFor?: (path: string) => { route?: string; screen?: string; path?: string } }): void
+navigatedTo(screen: string, labels?: { route?: string; path?: string }): void
+defaultLabelsFor(path: string): { route: string; screen: string; path: string }
 ```
-- Call once at startup. Every route change becomes a `nav` breadcrumb, and every entry
-  gets `route` (the pattern, `/orders/:id`), `path` (the real path) and `routeSource`.
-- When an app has called it, do not flag a missing `bc.nav` on route changes — it is
-  automatic. Suggest it for a single-page app that hand-writes `bc.nav` everywhere.
+- Call `enableNavigation` once at startup. Every page change becomes one `nav` breadcrumb, and
+  every entry gets `route` (the pattern, `/orders/:id`), `path` (the real path) and `screen`.
+- `labelsFor` names routes the app's own way; it must be synchronous. Flag the deprecated
+  `routeFor`, `cleanPath` and `path: false` options — `labelsFor` replaces all three.
+- Suggest `navigatedTo` only for apps whose screens change without the URL changing.
+- An app on Vue Router 4 or a React Router data router (6.4+, 7) should use the adapter
+  instead: `enableVueRouterNavigation(router)` from `/client/navigation/vue-router`, or
+  `enableReactRouterNavigation(router)` from `/client/navigation/react-router`. It takes
+  names from the router (Vue route `name`, React `handle.screen`). Flag a `labelsFor` that
+  re-lists the app's routes by hand in such an app.
 - A separate import on purpose: apps that do not use it ship none of it.
 
 Import `sendFeedback` from `firebase-structured-logger/client`:

package/skills/query-logs/SKILL.md

@@ -33,7 +33,7 @@ All entries written by firebase-structured-logger include these labels:
 | `screen` | Current screen name (falls back to `route` when the app never set one) |
 | `route` | Route pattern, e.g. `/orders/:id/items` — group by this (apps using `enableNavigation`) |
 | `path` | Real path, e.g. `/orders/1042/items` — one specific page or record; query string never stored |
-| `routeSource` | `router` (the app named the route) or `pattern` (ids replaced by rule) |
+| `routeSource` | **Deprecated, removed in 2.0.** `pattern` when the default id rule made the route |
 | `trace` | On a slow-trace WARNING: the trace's name, e.g. `app_boot` |
 | `run` | On a slow-trace WARNING: tells overlapping runs of one trace apart |
 | `slow` | `trace` (the whole run passed its limit) or `step` (one step passed its own) |