@gadicc/loom 1.27.0 → 1.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,28 @@
1
+ import "../../../_dnt.polyfills.js";
2
+ /**
3
+ * Browser-side Better Auth helpers. This module imports nothing, so it adds no
4
+ * dependency and is safe to reach from a consumer's own client module. Read
5
+ * globals through `globalThis`: a bare `window` becomes a build shim that is
6
+ * always defined, and pulls Node polyfills into the browser bundle.
7
+ */
8
+ type PendingSessionState = {
9
+ isPending: boolean;
10
+ };
11
+ /**
12
+ * Wraps Better Auth's `useSession` so a session reports pending only until the
13
+ * page's first answer.
14
+ *
15
+ * Better Auth marks a session with no data as pending again for every refetch,
16
+ * which it runs on focus, on reconnect and on a cross-tab session change. For a
17
+ * signed-out visitor that turns each of those into a pending state, so views
18
+ * waiting for the first answer unmount and re-check identity, and anything
19
+ * keyed on the session runs again. After the first answer this keeps the last
20
+ * settled state, which for a pending refetch is always "no session", until the
21
+ * new answer arrives.
22
+ *
23
+ * Server renders never settle, so hydration still starts from the pending
24
+ * state the server rendered.
25
+ */
26
+ export declare function createSettledSessionHook<TState extends PendingSessionState>(useSession: () => TState): () => TState;
27
+ export {};
28
+ //# sourceMappingURL=client.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/src/next/auth/client.ts"],"names":[],"mappings":"AAAA,OAAO,4BAA4B,CAAC;AAGpC;;;;;GAKG;AAEH,KAAK,mBAAmB,GAAG;IACzB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,SAAS,mBAAmB,EACzE,UAAU,EAAE,MAAM,MAAM,GACvB,MAAM,MAAM,CAWd"}
@@ -0,0 +1,32 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.createSettledSessionHook = createSettledSessionHook;
4
+ require("../../../_dnt.polyfills.js");
5
+ "use client";
6
+ /**
7
+ * Wraps Better Auth's `useSession` so a session reports pending only until the
8
+ * page's first answer.
9
+ *
10
+ * Better Auth marks a session with no data as pending again for every refetch,
11
+ * which it runs on focus, on reconnect and on a cross-tab session change. For a
12
+ * signed-out visitor that turns each of those into a pending state, so views
13
+ * waiting for the first answer unmount and re-check identity, and anything
14
+ * keyed on the session runs again. After the first answer this keeps the last
15
+ * settled state, which for a pending refetch is always "no session", until the
16
+ * new answer arrives.
17
+ *
18
+ * Server renders never settle, so hydration still starts from the pending
19
+ * state the server rendered.
20
+ */
21
+ function createSettledSessionHook(useSession) {
22
+ let settled = false;
23
+ return function useSettledSession() {
24
+ const session = useSession();
25
+ if (!session.isPending) {
26
+ if (typeof globalThis.document !== "undefined")
27
+ settled = true;
28
+ return session;
29
+ }
30
+ return settled ? { ...session, isPending: false } : session;
31
+ };
32
+ }
@@ -1,5 +1,6 @@
1
1
  type SessionQuery = {
2
2
  disableCookieCache?: boolean;
3
+ disableRefresh?: boolean;
3
4
  };
4
5
  type GetSessionArgs<THeaders> = {
5
6
  headers: THeaders;
@@ -20,9 +21,24 @@ export type CreateRequestAuthSessionReadersOptions<THeaders, TAuth extends Bette
20
21
  getHeaders: () => THeaders | Promise<THeaders>;
21
22
  profileEnvVar?: string;
22
23
  };
24
+ export type SessionReadOptions = {
25
+ disableCookieCache?: boolean;
26
+ /** Reads the session without extending it, for a check that only decides. */
27
+ disableRefresh?: boolean;
28
+ };
23
29
  export declare function createRequestAuthSessionReaders<THeaders, TAuth extends BetterAuthLike<THeaders, unknown>>(options: CreateRequestAuthSessionReadersOptions<THeaders, TAuth>): {
24
30
  getFreshSession: any;
25
31
  getSession: any;
32
+ /**
33
+ * Reads the session again on every call, unlike the cached readers above.
34
+ * An authorization boundary that re-checks after awaited work needs this:
35
+ * a cached read can still answer from before a revocation. Pass
36
+ * `disableRefresh` for a check that only decides, so deciding does not
37
+ * extend the session.
38
+ */
39
+ readSession: (readOptions?: SessionReadOptions) => Promise<InferAuthSession<TAuth, THeaders>>;
40
+ /** `readSession` with the cookie cache bypassed, and never cached. */
41
+ readFreshSession: (readOptions?: SessionReadOptions) => Promise<InferAuthSession<TAuth, THeaders>>;
26
42
  };
27
43
  export {};
28
44
  //# sourceMappingURL=server.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../src/src/next/auth/server.ts"],"names":[],"mappings":"AAEA,KAAK,YAAY,GAAG;IAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,KAAK,cAAc,CAAC,QAAQ,IAAI;IAC9B,OAAO,EAAE,QAAQ,CAAC;IAClB,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,KAAK,cAAc,CAAC,QAAQ,EAAE,QAAQ,IAAI;IACxC,MAAM,EAAE;QACN,OAAO,EAAE,QAAQ,CAAC;KACnB,CAAC;IACF,GAAG,EAAE;QACH,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;KACtE,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAC1B,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC/C,QAAQ,IACN,KAAK,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;AAEtC,MAAM,MAAM,sCAAsC,CAChD,QAAQ,EACR,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,IAC7C;IACF,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,UAAU,EAAE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAMF,wBAAgB,+BAA+B,CAC7C,QAAQ,EACR,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAE/C,OAAO,EAAE,sCAAsC,CAAC,QAAQ,EAAE,KAAK,CAAC;;;EAoCjE"}
1
+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../src/src/next/auth/server.ts"],"names":[],"mappings":"AAEA,KAAK,YAAY,GAAG;IAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,KAAK,cAAc,CAAC,QAAQ,IAAI;IAC9B,OAAO,EAAE,QAAQ,CAAC;IAClB,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,KAAK,cAAc,CAAC,QAAQ,EAAE,QAAQ,IAAI;IACxC,MAAM,EAAE;QACN,OAAO,EAAE,QAAQ,CAAC;KACnB,CAAC;IACF,GAAG,EAAE;QACH,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;KACtE,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAC1B,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC/C,QAAQ,IACN,KAAK,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;AAEtC,MAAM,MAAM,sCAAsC,CAChD,QAAQ,EACR,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,IAC7C;IACF,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,UAAU,EAAE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,6EAA6E;IAC7E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,wBAAgB,+BAA+B,CAC7C,QAAQ,EACR,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAE/C,OAAO,EAAE,sCAAsC,CAAC,QAAQ,EAAE,KAAK,CAAC;;;IAqC9D;;;;;;OAMG;gCAtCU,kBAAkB,KAC9B,OAAO,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAuC3C,sEAAsE;qCACtC,kBAAkB;EAGrD"}
@@ -7,11 +7,13 @@ function createRequestAuthSessionReaders(options) {
7
7
  async function readSession(readOptions = {}) {
8
8
  const startedAt = Date.now();
9
9
  const requestHeaders = await options.getHeaders();
10
+ const query = {
11
+ ...(readOptions.disableCookieCache ? { disableCookieCache: true } : {}),
12
+ ...(readOptions.disableRefresh ? { disableRefresh: true } : {}),
13
+ };
10
14
  const session = await options.auth.api.getSession({
11
15
  headers: requestHeaders,
12
- query: readOptions.disableCookieCache
13
- ? { disableCookieCache: true }
14
- : undefined,
16
+ query: Object.keys(query).length ? query : undefined,
15
17
  });
16
18
  if (options.env?.[profileEnvVar] === "1") {
17
19
  console.info(`[perf:authSession] disableCookieCache=${readOptions.disableCookieCache ? 1 : 0} total=${Date.now() - startedAt}ms`);
@@ -23,5 +25,15 @@ function createRequestAuthSessionReaders(options) {
23
25
  return {
24
26
  getFreshSession,
25
27
  getSession,
28
+ /**
29
+ * Reads the session again on every call, unlike the cached readers above.
30
+ * An authorization boundary that re-checks after awaited work needs this:
31
+ * a cached read can still answer from before a revocation. Pass
32
+ * `disableRefresh` for a check that only decides, so deciding does not
33
+ * extend the session.
34
+ */
35
+ readSession,
36
+ /** `readSession` with the cookie cache bypassed, and never cached. */
37
+ readFreshSession: (readOptions = {}) => readSession({ ...readOptions, disableCookieCache: true }),
26
38
  };
27
39
  }
@@ -102,6 +102,71 @@ The helper accepts only loopback hosts and origins by default. Do not spread it
102
102
  into production configuration or enable trusted proxy headers when requests can
103
103
  bypass or spoof the intended proxy boundary.
104
104
 
105
+ ## App layouts the manifest records
106
+
107
+ `loom.json` describes the app's shape; the checks follow it rather than one
108
+ layout. Record `modules.authRuntimeModule` when the Better Auth factory stays
109
+ free of environment reads and another module builds the instance: the shared
110
+ secret and session helpers may then live in either, and either may be the module
111
+ the client, route and server import. That module must import the configured auth
112
+ module, otherwise its text says nothing about the instance being checked.
113
+
114
+ The route may wrap its handlers, for example to fail closed while a migration
115
+ completes, as long as one `toNextJsHandler(<instance>)` call supplies every
116
+ exported `GET` and `POST`.
117
+
118
+ ## Request-scoped sessions
119
+
120
+ `createRequestAuthSessionReaders` returns four readers. `getSession` and
121
+ `getFreshSession` are request-cached, so within one request each reads the
122
+ cookie once, which suits page and layout reads. `readSession` and
123
+ `readFreshSession` read again on every call.
124
+
125
+ An authorization boundary that re-checks after awaited work needs an uncached
126
+ read: a cached one can still answer from before a revocation. Use
127
+ `readFreshSession` there, and pass `disableRefresh` for a check that only
128
+ decides, so deciding does not extend the session. Validate identity and expiry
129
+ where you read.
130
+
131
+ An app may still own that reader, for example when it takes explicit headers so
132
+ tests and scripts can call it outside a request. Record
133
+ `requestSessionReaders: "app-owned"` then, so the check expects it.
134
+
135
+ ## Browser session state
136
+
137
+ Better Auth marks a session with no data as pending again for every refetch, and
138
+ it refetches on focus, on reconnect and on a cross-tab change. For a signed-out
139
+ visitor each of those becomes a pending state, so views waiting for the first
140
+ answer unmount and re-check identity. Wrap the client's hook once:
141
+
142
+ ```ts
143
+ "use client";
144
+
145
+ import { createSettledSessionHook } from "@gadicc/loom/next/auth/client";
146
+
147
+ export const authClient = createAuthClient({/* app plugins */});
148
+ export const useSession = createSettledSessionHook(authClient.useSession);
149
+ ```
150
+
151
+ The wrapper reports pending only until the page's first answer, then keeps the
152
+ last settled state, which for a pending refetch is always "no session". Server
153
+ renders never settle it, so hydration still starts from the server's state.
154
+
155
+ That module imports nothing and reads globals through `globalThis`. A bare
156
+ `window` in package source becomes a build shim that is always defined, and
157
+ pulls Node polyfills into the browser bundle; `scripts/build_npm.ts` guards the
158
+ emitted browser entrypoints against both.
159
+
160
+ ## Anonymous identity checks
161
+
162
+ An endpoint that answers "who is signed in" to a page should return 200 with a
163
+ null user for anonymous visitors, not 401. Anonymous pages ask on each load and
164
+ tab refocus, and browsers log every 401 as a failed request, which fills the
165
+ console during ordinary anonymous use. Keep 401 for endpoints that refuse to do
166
+ the work without a session. Clients cached before such a change must already
167
+ accept the new body: an old client that treats a null user as malformed shows an
168
+ error until it reloads.
169
+
105
170
  ## Local test login
106
171
 
107
172
  Developer UI login is distinct from a production-build E2E auth harness. Use
@@ -0,0 +1,90 @@
1
+ ---
2
+ name: modernize-app
3
+ description: Modernize an existing legacy web app toward Loom through staged tooling, framework, authentication, persistence and client-data migrations. Use for an app-wide modernization, especially Mongo/Gongo applications; use upgrade-deps alone for a dependency-only update and loom-scaffold for a new app.
4
+ ---
5
+
6
+ # Modernize an Existing App
7
+
8
+ Preserve the useful product and its data while replacing the underlying stack in
9
+ reviewable stages. Discover the actual starting point: recollection, old config
10
+ files and a dependency's presence do not establish which runtime paths are used.
11
+ Match the requested phase: for research-only work, inspect and design without
12
+ beginning application changes or provisioning resources. Treat the rollout
13
+ reference as acceptance criteria, not a ready-to-run recipe.
14
+
15
+ ## Establish a plan that can survive implementation
16
+
17
+ Use `loom` first in a consumer, read `loom.json`, and follow its recorded
18
+ tooling and feature contracts. If `loom.json` is absent, including an older
19
+ partial Loom adoption, inspect the existing tooling, imports and wrappers before
20
+ using existing-app adoption; do not scaffold over them. Use the matching
21
+ installed feature skill when adopting or changing a Loom feature.
22
+
23
+ Record active routes, important user journeys, authoritative services, server
24
+ and browser data, deployed runtime/region, branch/worktree, verification
25
+ commands and independent backup coverage. Classify findings as observed,
26
+ operator-decided, locally verified, provider-verified or pending. Keep current
27
+ status separate from historical checkpoint notes.
28
+
29
+ Ask about ambiguous product behavior before encoding it: ownership versus
30
+ access, who can create or publish, anonymous adoption, required offline use,
31
+ supported devices, reauthentication and recovery expectations. Continue
32
+ independent work. Reuse explicit decisions and authorization; do not make users
33
+ approve the same choice after every resume or commit.
34
+
35
+ Read only the relevant reference:
36
+
37
+ - [Architecture and characterization](references/architecture-and-characterization.md)
38
+ for feature boundaries, tests, tooling upgrades and retained formats.
39
+ - [Identity and data](references/identity-and-data.md) for Gongo/internal-auth
40
+ or NextAuth bridges, canonical IDs, SQL constraints and import preservation.
41
+ - [Offline data and media](references/offline-and-media.md) for browser data,
42
+ queued work, private downloads, uploads and rendered resource dependencies.
43
+ - [Rollout and shared work](references/rollout-and-shared-work.md) for provider
44
+ placement, rehearsals, production activation and extracting Loom improvements.
45
+
46
+ ## Order by dependencies, with useful intermediate behavior
47
+
48
+ Once implementation is authorized, establish reproducible checks and
49
+ characterize the next changing boundary. Run `upgrade-deps` for the dependency
50
+ campaign, grouping coupled packages and recording supported deferrals. Introduce
51
+ application services over the current authoritative store; port simpler features
52
+ first. Prepare SQL schemas and pure import planners locally, then exercise
53
+ protected real input without publishing private fixtures. Build browser recovery
54
+ before retiring any legacy store or protocol it depends on.
55
+
56
+ Choose authentication and persistence release boundaries from actual ID/session
57
+ dependencies. A verified NextAuth-to-Gongo bridge can allow staged replacement;
58
+ it is an option, not a mandatory intermediate destination. A database adapter is
59
+ useful only when its supported synchronization subset costs less than migrating
60
+ remaining features. Avoid implementing a generic Mongo emulator by accident.
61
+
62
+ Keep one authoritative writer at each stage. A passing schema, parser,
63
+ repository or provider probe is a completed foundation, not runtime activation.
64
+ Enable a feature only after its identity, permission, transport, persistence, UI
65
+ and recovery boundaries work together. Do not postpone integration tests that
66
+ could disprove the architecture until every foundation is finished.
67
+
68
+ ## Review and leave usable checkpoints
69
+
70
+ Before a meaningful commit, use `loom-torvalds-review` with the relevant app or
71
+ shared-package profile. Challenge account switching, stale callbacks, retries,
72
+ concurrent changes, bypass paths, partial failure, existing clients and
73
+ recovery. Use an independent reviewer when delegation is authorized and
74
+ valuable; otherwise make the adversarial pass explicit. Tie findings to
75
+ reachable behavior and add meaningful regression checks. Review the final
76
+ integrated diff, not only a staged subagent patch, and rerun checks affected by
77
+ review fixes.
78
+
79
+ Respect the operator's model and usage budget. When delegated implementation is
80
+ authorized, give workers bounded tasks and only the context they need; retain
81
+ the requested orchestration and review ownership. Reuse established baseline and
82
+ identical-artifact evidence instead of repeating unchanged checks. Repeat checks
83
+ when edits, failures or unresolved concerns justify them.
84
+
85
+ When commits are authorized, commit each passing compatibility unit with a
86
+ consistent manifest/lockfile and the repository's attribution rules. Keep shared
87
+ configuration and integration under one owner when work runs in parallel. Record
88
+ what changed, exact verification scope, limitations, activation state and next
89
+ gate. Continue authorized work without routine confirmation; publishing,
90
+ provider changes and cutover remain bounded by the user's actual authorization.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Modernize a Legacy App"
3
+ short_description: "Upgrade legacy apps through verified migration stages"
4
+ default_prompt: "Use $modernize-app to inspect this legacy app and carry out a staged Loom modernization."
@@ -0,0 +1,205 @@
1
+ # Architecture and characterization
2
+
3
+ ## Establish what exists before replacing it
4
+
5
+ Trace entry points to their actual reads, writes, identity and external effects.
6
+ An empty RPC router can be removed after usage/build checks; a populated one
7
+ needs a caller and behavior migration. Inspect route files before proposing a
8
+ Pages-to-App Router migration. Compare live deployment settings with local
9
+ configuration rather than assuming either mirrors the other.
10
+
11
+ Reference apps provide patterns, not a version set or universal product policy.
12
+ Compare richer behaviors and missing cases. A cache freshness TTL is not an
13
+ authorization lease; a whole-database cleanup helper may destroy an outbox in
14
+ another app. Use Loom's registries when doing shared extraction.
15
+
16
+ Make a small feature matrix with authority, read/write entry points,
17
+ permissions, offline necessity, unsynchronized state and intended replacement.
18
+ Trace code that bypasses a nominal data adapter: auth adapters, uploads, jobs
19
+ and integrations often use the database directly. Identify unused experiments
20
+ separately from active systems. An ingestion target and a retrieval target can
21
+ have drifted; moving the wrong one does not migrate the product.
22
+
23
+ ## Pick the smallest useful service boundary
24
+
25
+ For online pages, Server Components can call server query services directly and
26
+ ordinary forms can use authenticated Server Actions. RSC does not provide
27
+ durable client state or replace every transport. Keep versioned callable
28
+ endpoints for offline outboxes, streaming, direct uploads and binary/rendered
29
+ responses. Do not persist deployment-specific Server Action references as
30
+ durable offline commands.
31
+
32
+ When consolidating generated-media routes, derive a closed registry and
33
+ parameter contract from actual callers. Keep old URLs as thin wrappers over the
34
+ shared service. Preserve genuine list-valued parameters, their order and
35
+ meaningful empty values; do not confuse them with repeated scalar keys. A widget
36
+ exporting live client state needs its own server-rendering contract before
37
+ adding its slug.
38
+
39
+ Reuse authorization and domain services across old and new entry points. A
40
+ database transition must not leave old generic mutation endpoints able to bypass
41
+ the new command. Constrain them or migrate coupled callers in the same unit. A
42
+ brief full-snapshot bridge can be simpler than preserving a flawed timestamp
43
+ delta protocol; measure its bounded data size and remember that an omitted item
44
+ does not automatically evict a legacy cache.
45
+
46
+ Separate an operation's protocol version, data schema version, concurrency
47
+ version, compiler identity and output compatibility profile. A compatible
48
+ compiler update should not make older stored output unreadable; a new renderer
49
+ profile requires explicit reader support.
50
+
51
+ ## Characterize behavior that the migration could change
52
+
53
+ Prioritize permissions, exact source/data round trips, concurrency, uncertain
54
+ acknowledgements, scheduling boundaries, anonymous adoption, critical form
55
+ values, stream framing and actual rendering. Extract pure logic from
56
+ editor/framework side effects where practical. Do not turn legacy library method
57
+ names into the permanent test interface or preserve an obvious defect as
58
+ required behavior.
59
+
60
+ Use scoped coverage that includes unimported files in selected modules. Describe
61
+ its scope honestly; high coverage of extracted modules is not whole-app
62
+ coverage. Expand it as meaningful boundaries move. Do not weaken assertions or
63
+ thresholds merely to accommodate a dependency upgrade.
64
+
65
+ Use old/new comparisons for scheduling, astronomy, compiler/source maps and
66
+ serialization. Fix clocks/locales/timezones and preserve absent versus zero/null
67
+ states. Test actual controls for partial dates and clearing; a schema test alone
68
+ does not show what a third-party picker submits. Inspect package exports and
69
+ native binaries, not only version ranges.
70
+
71
+ Standalone harnesses should use the package instances and runtime realms of the
72
+ boundary they exercise. CJS/ESM entry points or duplicate installations can
73
+ create distinct class identities and fail `instanceof` for otherwise equivalent
74
+ values. Diagnose a harness mismatch before weakening validation. If mixed
75
+ instances occur in the supported runtime, treat that as a compatibility issue to
76
+ resolve and test; changing only the fixture would hide the problem. Check the
77
+ runtime export shape too: a standalone CJS loader can expose an ESM schema's
78
+ re-exports beneath a default namespace. Match the supported loader before
79
+ changing app exports to satisfy the harness.
80
+
81
+ Real browser checks matter for contenteditable/CodeMirror, hook-driven
82
+ rendering, selection, clipboard, service workers, IndexedDB and multi-tab
83
+ lifetimes. Keep known baseline failures identifiable, then compare old/new
84
+ behavior. A documented hook-order workaround may require retaining the current
85
+ renderer and disabling a new compiler optimization until its architecture is
86
+ deliberately changed.
87
+
88
+ Widget mocks must preserve lifecycle boundaries relevant to the failure. An
89
+ eager editor mock can hide a lost source update before the real view mounts.
90
+ Verify initial text and preview after delayed creation, and that a late view
91
+ cannot restore content after access is locked. Inspect whether controlled value
92
+ updates emit the same change callback as user input before relying on that
93
+ callback for compilation or draft persistence.
94
+
95
+ ## Choose the acceptance environment early
96
+
97
+ Inspect Loom and the reference apps for developer test-user flows before asking
98
+ the operator to repeat long multi-account journeys on Preview. Automate ordinary
99
+ permissions, forms, account switching and offline behavior against isolated
100
+ local data. Keep a smaller deployed pass for actual OAuth callbacks, platform
101
+ packaging, database integration and object-storage behavior that local services
102
+ cannot prove. Synthetic sessions can prove the application's authorization and
103
+ lifecycle contracts, but they cannot prove provider consent, callback
104
+ registration, cookie behavior or account linking. Keep the real OAuth journey as
105
+ its own deployed gate.
106
+
107
+ Keep developer login and production-build test sessions separate. Shared
108
+ developer login can own explicit opt-in, local request checks, fixed identity
109
+ selection and cookie forwarding; the app owns identity persistence and
110
+ permission grants. An identity named "admin" must not silently bypass a separate
111
+ grant fixture. Follow the installed `loom-auth` guidance when its shared helper
112
+ is available.
113
+
114
+ For service-worker acceptance, use the app's production build when development
115
+ mode disables the worker. An auth library's official test helper can create real
116
+ sessions through a separate command without enabling a deployed test-login
117
+ route. Bind the command to synthetic targets, validate sessions with the actual
118
+ runtime auth configuration, and keep browser storage-state files private and
119
+ ignored.
120
+
121
+ Exercise real local storage protocols where practical, including conditional
122
+ write retries and subsequent reads. A passing local adapter does not prove cloud
123
+ CORS, credentials or exact provider behavior. Keep any local transport exception
124
+ explicit and scoped; preserve the cloud adapter's authorization and validation.
125
+
126
+ Test cold loading and reconnect separately from steady-state requests. A private
127
+ view can register while account verification is still in progress, miss its
128
+ first permission check, and later display a cached grant without checking
129
+ revocation. Coalesce readiness retries without looping on the state changes
130
+ caused by those same requests. Review every caller of shared identity
131
+ activation, since an older verification may change local authority before a
132
+ newer check rejects it as stale. Also interrupt an already-started permission
133
+ request with account activation: readiness gating alone does not repair a
134
+ cancelled request. Exercise registration of already-cached resources with the
135
+ real coordinator: asynchronous discovery can invalidate a request before its
136
+ first network call. A lock reason may be shared by that discovery and the
137
+ request's own successful cache update. Track whether the permission response was
138
+ accepted, and retry pre-acceptance cancellation without turning accepted cache
139
+ changes or ordinary network failures into a loop. When replacing awaited work
140
+ with queued callbacks, preserve ordering required by later save, publication or
141
+ cleanup operations. Update tests so their promises are actually in flight before
142
+ exercising cancellation or sign-out.
143
+
144
+ When a browser session closes without evidence, inspect driver stderr before
145
+ diagnosing an application crash or retrying. Restricted script contexts may omit
146
+ ordinary globals, and an uncaught event-listener error can terminate the driver.
147
+
148
+ ## Upgrade tooling without bundling a product rewrite
149
+
150
+ Follow `upgrade-deps`; re-query supported versions and migration guidance when
151
+ the work happens. Align actual executing Node/Deno, package-manager pins, CI and
152
+ deployment targets. Preserve intentional loaders and build modes while moving
153
+ framework/runtime/adapter families. Read installed framework docs where
154
+ available. Migrate formatter defaults deliberately and separate broad formatting
155
+ from behavior changes; lint-driven React key changes can alter state.
156
+
157
+ After dependency patches or code generation, inspect the artifact actually
158
+ served. A package file can be correct while an incremental framework cache still
159
+ emits old code. Use clean generated output when evidence calls for it; do not
160
+ delete user data or lockfiles to make verification pass. Match source/artifact
161
+ identities between isolated tests and the integrated app.
162
+
163
+ A repository alert banner is not a dependency audit result: its count can differ
164
+ from the API and can outlive manifests removed from the default branch. Resolve
165
+ alerts against the current default-branch manifests and lockfile, then trace
166
+ each advisory through the installed dependency path to its actual input and
167
+ sink. An unreachable trigger can justify scheduling a patch after a release, but
168
+ it is not security clearance for the dependency or for unrelated alerts.
169
+
170
+ When diagnosing a Vercel prebuilt deployment mismatch, rebuild from a fresh real
171
+ dependency tree. Reused dependencies can conceal packages or files that the
172
+ declared install and deployment artifact do not contain. When the installed CLI
173
+ supports it, use `vercel build --standalone` to inline external file references,
174
+ then prove every packaged path remains inside the standalone output root.
175
+ Inspect the complete upload graph rather than only regular files: follow
176
+ symlinks and resolve `FileFsRef` and `filePathMap` entries to their final
177
+ packaged targets. A successful build or upload summary does not establish that
178
+ this graph is complete. Nor does enumerating every traced edge prove the tracer
179
+ discovered data loaded from a runtime-computed path. For dynamic fonts, native
180
+ data or similar resources, verify the physical packaged file and execute the
181
+ built route that opens it.
182
+
183
+ For native/WASM resources, exercise the built public route and inspect
184
+ deployment asset traces. A loader working in unit tests can be rewritten by the
185
+ bundler or retain a build-machine path. Verify every wrapper carries the
186
+ required server assets, and exercise repeated calls in one process: shared
187
+ initialization can fail even when each isolated test succeeds.
188
+
189
+ Next's NFT trace can name an asset through a pnpm package symlink while the
190
+ final standalone artifact omits its physical target. Check the actual packaged
191
+ and deployed file, then exercise native/WASM initialization; a trace entry alone
192
+ proves neither inclusion nor loadability.
193
+
194
+ An RSC page can carry a runtime exception with HTTP 200. Inspect the decoded RSC
195
+ result and runtime error. Under current Next, do not pass the Next `Link`
196
+ function through MUI's `component` prop across a server/client boundary;
197
+ instantiate that composition in a client component. Client-only usage remains
198
+ valid.
199
+
200
+ Keep stored content formats stable through persistence migration unless a change
201
+ is necessary. Evaluate replacement editors independently with real constructs,
202
+ round-trip conversion, diagnostics and the intended editor audience. Preserve
203
+ exact originals and distinguish semantic comparison rules from transformations
204
+ applied to stored data. Defer collaboration or other product work when outside
205
+ the agreed milestone.