@rohal12/spindle 0.59.11 → 0.59.13

package/dist/pkg/story-variables.js

@@ -11082,7 +11082,8 @@ var VALID_VAR_TYPES = new Set([
 ]);
 function inferSchema(value) {
 	if (Array.isArray(value)) return { type: "array" };
-	if (value !== null && typeof value === "object") {
+	if (value === null) return { type: "null" };
+	if (typeof value === "object") {
 		const fields = /* @__PURE__ */ new Map();
 		for (const [key, val] of Object.entries(value)) fields.set(key, inferSchema(val));
 		return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.59.11",
+  "version": "0.59.13",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",

package/src/components/macros/Computed.tsx

@@ -5,7 +5,7 @@ import { deepEqualStrict } from '../../structural';
 import { defineMacro } from '../../define-macro';
 import { MacroError, logMacroError } from './MacroError';
 import { currentSourceLocation } from '../../utils/source-location';
-import { checkVariableName } from '../../utils/namespace';
+import { checkVariableName, ownValue } from '../../utils/namespace';
 
 /**
  * The previous output before the first successful evaluation. Distinct from
@@ -39,7 +39,7 @@ function assignmentArgs(
 /**
  * Evaluate `expr` against the current values — the store's state and the
  * enclosing locals scope's live values (`getLocals`) — and write the result
- * to the target if it differs from the previous output (always, the first
+ * to the target if it differs from the previous output or the target's value (always, the first
  * time). Reading live values rather than the render's snapshot means the
  * first computation sees a local a preceding {set} just assigned (the scope's
  * context value only catches up on its re-render), and the first computation
@@ -53,22 +53,39 @@ function computeAndApply(
   getLocals: () => Record<string, unknown>,
   rawArgs: string,
   prevRef: { current: unknown },
+  lastNavigation: { current: number },
   localsUpdate: ((key: string, value: unknown) => void) | null,
 ): void {
   // Before evaluating: the expression may navigate away from this passage
   const location = currentSourceLocation();
   let newValue: unknown;
+  let current: unknown = prevRef.current;
+  let navigated = false;
+  const { navigationId } = useStoryStore.getState();
   try {
     // In program order, also when mutation code sets this off
     const { variables, temporary, transient } = readState();
+    // A navigation (or restored session) resets the temporary namespace,
+    // which a persistent {computed} survives: the target is then gone though
+    // the result is unchanged, and is written again. Between navigations a
+    // target the story removed or set itself stays as it is.
+    if (!isLocal) {
+      current = ownValue(isTemp ? temporary : variables, name);
+      navigated = navigationId !== lastNavigation.current;
+    }
     newValue = evaluate(expr, variables, temporary, getLocals(), transient);
   } catch (err) {
     logMacroError(`computed ${rawArgs}`, err, location);
     return;
   }
 
+  lastNavigation.current = navigationId;
+
   // Strict: a change of only the aliases inside the result is a change
-  if (!deepEqualStrict(prevRef.current, newValue)) {
+  if (
+    !deepEqualStrict(prevRef.current, newValue) ||
+    (navigated && !deepEqualStrict(current, newValue))
+  ) {
     prevRef.current = newValue;
     if (isLocal) {
       try {
@@ -93,8 +110,6 @@ defineMacro({
     { name: 'expression', type: 'expression', required: true },
   ],
   render({ rawArgs }, ctx) {
-    const [mergedVars, mergedTemps, mergedLocals, mergedTrans] = ctx.merged!;
-
     let target: string;
     let expr: string;
     try {
@@ -113,6 +128,8 @@ defineMacro({
     const localsUpdate = isLocal ? ctx.update : null;
 
     const prevOutput = ctx.hooks.useRef<unknown>(UNSET);
+    // The navigation the target was last checked in
+    const lastNavigation = ctx.hooks.useRef(-1);
 
     const compute = () =>
       computeAndApply(
@@ -123,6 +140,7 @@ defineMacro({
         ctx.getValues,
         rawArgs,
         prevOutput,
+        lastNavigation,
         localsUpdate,
       );
 
@@ -133,13 +151,9 @@ defineMacro({
     }
 
     // The merged values only decide when to recompute; computeAndApply reads
-    // the current ones.
-    ctx.hooks.useLayoutEffect(compute, [
-      mergedVars,
-      mergedTemps,
-      mergedLocals,
-      mergedTrans,
-    ]);
+    // the current ones. The tuple is renewed with them and with the render
+    // counts, which rendered() / hasRendered() read.
+    ctx.hooks.useLayoutEffect(compute, [ctx.merged]);
 
     return null;
   },

package/src/components/macros/For.tsx

@@ -3,8 +3,10 @@ import { LocalsValuesContext } from '../../markup/render';
 import { defineMacro } from '../../define-macro';
 import { MacroError } from './MacroError';
 import { stableKey } from '../../utils/stable-key';
+import { controlEditVersion, editedItem } from '../../utils/control-edits';
 import type { ASTNode } from '../../markup/ast';
 import { checkVariableName } from '../../utils/namespace';
+import { readState } from '../../execute-mutation';
 import { LocalsScope } from './locals-scope';
 
 /**
@@ -76,6 +78,14 @@ function ForIteration({
   );
 }
 
+/** What {for} remembers of its iterations between renders. */
+interface IterationKeys {
+  contents: string[];
+  generations: number[];
+  next: number;
+  edits: number;
+}
+
 defineMacro({
   name: 'for',
   block: true,
@@ -88,6 +98,12 @@ defineMacro({
   ],
   render({ rawArgs, children = [] }, ctx) {
     const parentValues = useContext(LocalsValuesContext);
+    const keys = ctx.hooks.useRef<IterationKeys>({
+      contents: [],
+      generations: [],
+      next: 0,
+      edits: controlEditVersion(),
+    }).current;
 
     let loop: ReturnType<typeof loopArgs>;
     let list: unknown[];
@@ -112,9 +128,29 @@ defineMacro({
     }
 
     const { itemVar, indexVar } = loop;
+    // An iteration is remounted when its item's contents change, so mount-only
+    // macros run again for the new item (#45) -- unless the change is a
+    // reader editing the item through a control: remounting would drop the
+    // control's focus after the first keystroke.
+    const since = keys.edits;
+    const { variables } = readState();
+    keys.edits = controlEditVersion();
+    const generations = list.map((item, i) => {
+      const contents = stableKey(item);
+      if (
+        keys.generations[i] === undefined ||
+        (contents !== keys.contents[i] &&
+          !editedItem(since, variables, list, item, i))
+      ) {
+        keys.generations[i] = keys.next++;
+      }
+      keys.contents[i] = contents;
+      return keys.generations[i]!;
+    });
+    keys.contents.length = keys.generations.length = list.length;
     const content = list.map((item, i) => (
       <ForIteration
-        key={`${i}-${stableKey(item)}`}
+        key={`${i}-${generations[i]}`}
         parentValues={parentValues}
         itemVar={itemVar}
         itemValue={item}

package/src/components/macros/Type.tsx

@@ -49,7 +49,10 @@ defineMacro({
     const containerRef = useRef<HTMLSpanElement>(null);
     const innerRef = useRef<HTMLSpanElement>(null);
     const [clip, setClip] = useState<string | undefined>();
-    const [totalChars, setTotalChars] = useState(0);
+    // Null until the content has been measured: zero characters is then a
+    // result (nothing to animate), not a pending measurement.
+    const [measured, setMeasured] = useState<number | null>(null);
+    const totalChars = measured ?? 0;
     const [visibleChars, setVisibleChars] = useState(0);
     const visibleCharsRef = useRef(0);
     visibleCharsRef.current = visibleChars;
@@ -59,7 +62,7 @@ defineMacro({
     useEffect(() => {
       if (containerRef.current) {
         const text = containerRef.current.textContent || '';
-        setTotalChars(text.length);
+        setMeasured(text.length);
       }
     });
 
@@ -81,7 +84,8 @@ defineMacro({
       return () => clearInterval(timer);
     }, [totalChars, speed]);
 
-    const done = visibleChars >= totalChars && totalChars > 0;
+    // Empty text can still become reactive text later, which restarts typing
+    const done = measured !== null && visibleChars >= totalChars;
 
     // Clip to the characters revealed so far, as laid out: remeasured when
     // the count changes and when the width the text wraps in does.
@@ -117,7 +121,7 @@ defineMacro({
           class="macro-type-inner"
           style={{
             display: 'inline',
-            visibility: totalChars === 0 ? 'hidden' : 'visible',
+            visibility: measured === null ? 'hidden' : 'visible',
             clipPath: clip,
           }}
         >

package/src/components/macros/Widget.tsx

@@ -1,6 +1,4 @@
-import { registerWidget } from '../../widgets/widget-registry';
-import { astContainsChildren } from '../../widgets/ast-scanner';
-import { registerBlockMacro, type ASTNode } from '../../markup/ast';
+import { registerWidgetDef } from '../../widgets/register-widget-def';
 import { defineMacro } from '../../define-macro';
 import { checkVariableName } from '../../utils/namespace';
 import { MacroError } from './MacroError';
@@ -10,22 +8,6 @@ import {
   type WidgetDef,
 } from '../../widgets/widget-def';
 
-/**
- * Register the widget a definition declares, with its body. Widgets whose
- * body renders {@children} take a closing tag, so they are registered as
- * block macros too: passages parsed later nest their content. A parameter
- * that no namespace can hold throws (see registerWidget), registering
- * nothing.
- */
-export function registerWidgetDef(
-  { name, params }: WidgetDef,
-  body: ASTNode[],
-): void {
-  const isBlock = astContainsChildren(body);
-  registerWidget(name, body, params, isBlock);
-  if (isBlock) registerBlockMacro(name);
-}
-
 defineMacro({
   name: 'widget',
   block: true,

package/src/components/macros/WidgetInvocation.tsx

@@ -46,16 +46,9 @@ function WidgetContent({
 
   const childrenValue = invocationChildren?.length ? invocationChildren : null;
 
-  // Parameterized widgets always get their own local scope, even when invoked
-  // without arguments: missing parameters shadow outer locals as undefined.
-  if (params.length === 0) {
-    return (
-      <WidgetChildrenContext.Provider value={childrenValue}>
-        {renderNodes(body, renderOptions)}
-      </WidgetChildrenContext.Provider>
-    );
-  }
-
+  // Every widget gets its own local scope, even when it declares no
+  // parameters or is invoked without arguments: missing parameters shadow
+  // outer locals as undefined, and the body's own locals stay in the widget.
   const argExprs = rawArgs ? splitArgs(rawArgs) : [];
   const values: unknown[] = [];
 

package/src/define-macro.ts

@@ -10,6 +10,7 @@ import {
   useMemo,
 } from 'preact/hooks';
 import { useInterpolate } from './hooks/use-interpolate';
+import { noteControlEdit } from './utils/control-edits';
 import { useMergedLocals } from './hooks/use-merged-locals';
 import { useRenderOptions } from './hooks/use-render-options';
 import {
@@ -228,6 +229,7 @@ export function defineMacro<const P extends readonly ParameterDef[] = []>(
       // In program order, also when mutation code performs the input
       ctx.getValue = () => getByPath(readState().variables, segments);
       ctx.setValue = (value: unknown) => {
+        noteControlEdit(segments);
         // The commit mutation code uses, which keeps the references among
         // variables: a write to a draft copies only the path written, and
         // other variables sharing the object would keep the old one.

package/src/execute-mutation.ts

@@ -138,6 +138,32 @@ export function frozenCopy<T>(value: T): T {
   return freeze(cloneValue(value), true);
 }
 
+/** Whether `value` and everything it holds is frozen. */
+function deeplyFrozen(value: unknown, seen = new Set<object>()): boolean {
+  if (typeof value !== 'object' || value === null || seen.has(value)) {
+    return true;
+  }
+  // Leaves a freeze cannot lock (typed array elements) and that a copy would
+  // detach from what they share (a buffer): handed out as they are
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return true;
+  if (!Object.isFrozen(value)) return false;
+  seen.add(value);
+  return Reflect.ownKeys(value).every((key) => {
+    const desc = Object.getOwnPropertyDescriptor(value, key);
+    return !desc || !('value' in desc) || deeplyFrozen(desc.value, seen);
+  });
+}
+
+/**
+ * A value read from the store, made safe to hand out: the store holds plain
+ * values frozen, but not registered class instances, whose methods could
+ * change the recorded history through the live object. Such a value is
+ * returned as a frozen copy, like a read inside mutation code.
+ */
+export function readOnlyValue<T>(value: T): T {
+  return deeplyFrozen(value) ? value : frozenCopy(value);
+}
+
 /**
  * Apply a write that reached the store while mutations execute to their
  * `work` and `base` copies (see MutationScope), so the code sees it and

package/src/hooks/use-modal-focus.ts

@@ -9,8 +9,9 @@ const FOCUSABLE = [
   'select:not([disabled])',
   'textarea:not([disabled])',
   'iframe',
-  '[contenteditable="true"]',
-  '[tabindex]:not([tabindex="-1"])',
+  'summary',
+  '[contenteditable]',
+  '[tabindex]',
 ].join(',');
 
 /**
@@ -27,15 +28,76 @@ function isRendered(el: HTMLElement): boolean {
   return true;
 }
 
+/** The `tabindex` of `el` as an integer, or null when absent or invalid. */
+function tabIndexAttr(el: HTMLElement): number | null {
+  const raw = el.getAttribute('tabindex');
+  if (raw === null || !/^\s*[+-]?\d+\s*$/.test(raw)) return null;
+  return parseInt(raw, 10);
+}
+
+/**
+ * Whether the tab key can reach `el`: a negative tabindex only allows
+ * scripted focus, and of a radio group the browser tabs to the checked
+ * member only (the first one when none is checked).
+ */
+function isTabStop(el: HTMLElement): boolean {
+  const tabIndex = tabIndexAttr(el);
+  if (tabIndex !== null && tabIndex < 0) return false;
+  // Only an editing host takes focus, not `contenteditable="false"` or
+  // content nested in a host
+  if (
+    el.hasAttribute('contenteditable') &&
+    !el.matches('a[href], button, input, select, textarea, iframe, summary') &&
+    (!el.isContentEditable || el.parentElement?.isContentEditable)
+  ) {
+    return false;
+  }
+  // Only a details element's first summary child is its toggle
+  if (el.localName === 'summary') {
+    const details = el.parentElement;
+    if (
+      details?.localName !== 'details' ||
+      Array.from(details.children).find((c) => c.localName === 'summary') !== el
+    ) {
+      return tabIndex !== null;
+    }
+  }
+  if (el instanceof HTMLInputElement && el.type === 'radio' && el.name) {
+    const group = Array.from(
+      (
+        el.form ?? (el.getRootNode() as ParentNode)
+      ).querySelectorAll<HTMLInputElement>('input[type="radio"]'),
+    ).filter((r) => r.name === el.name && r.form === el.form && !r.disabled);
+    const stop = group.find((r) => r.checked) ?? group[0];
+    return el === stop;
+  }
+  return true;
+}
+
+/**
+ * The elements of `root` in the order Tab visits them: positive tabindexes
+ * first, ascending, then the others in document order.
+ */
 function focusables(root: HTMLElement): HTMLElement[] {
-  return Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(
+  const stops = Array.from(
+    root.querySelectorAll<HTMLElement>(FOCUSABLE),
+  ).filter(
     (el) =>
       !el.hidden &&
       !el.closest('[hidden], [inert]') &&
       // Also covers controls disabled by a <fieldset disabled> ancestor
       !el.matches(':disabled') &&
-      isRendered(el),
+      isRendered(el) &&
+      isTabStop(el),
   );
+  const positive = (el: HTMLElement) => Math.max(tabIndexAttr(el) ?? 0, 0);
+  // Array.prototype.sort is stable: equal tabindexes keep document order
+  return [
+    ...stops
+      .filter((el) => positive(el) > 0)
+      .sort((a, b) => positive(a) - positive(b)),
+    ...stops.filter((el) => positive(el) === 0),
+  ];
 }
 
 interface ModalEntry {

package/src/index.tsx

@@ -27,7 +27,7 @@ import {
 import { blockWidgetNames, parseWidgetDef } from './widgets/widget-def';
 import { parseMarkup } from './markup/parse';
 import { registerBlockMacro } from './markup/ast';
-import { registerWidgetDef } from './components/macros/Widget';
+import { registerWidgetDefinitions } from './widgets/register-widget-def';
 import { errorMessage } from './utils/error-message';
 import type { ASTNode } from './markup/ast';
 import './macros/register-builtins';
@@ -193,6 +193,14 @@ export function boot() {
   // Enter runtime phase — handlers registered from here on are cleaned on restart
   enterRuntimePhase();
 
+  // Pass 2: Full parse and register widgets from passages tagged "widget",
+  // before StoryInit runs so that it can invoke them
+  for (const [, passage] of storyData.passages) {
+    if (passage.tags.includes('widget')) {
+      registerWidgetDefinitions(parseMarkup(passage.content), passage.name);
+    }
+  }
+
   // Run StoryInit, restore the session if the page was refreshed, and fire
   // storyinit after all state is settled (defaults + StoryInit + session)
   initializeStory(loadSession(storyData.ifid));
@@ -205,27 +213,6 @@ export function boot() {
   ];
   if (markup.length > 0) stopWithErrors(markup);
 
-  // Pass 2: Full parse and register widgets from passages tagged "widget"
-  for (const [, passage] of storyData.passages) {
-    if (passage.tags.includes('widget')) {
-      const widgetAST = parseMarkup(passage.content);
-      for (const node of widgetAST) {
-        if (node.type === 'macro' && node.name === 'widget' && node.rawArgs) {
-          // Read and registered as the {widget} macro does
-          const def = parseWidgetDef(node.rawArgs);
-          try {
-            registerWidgetDef(def, node.children as ASTNode[]);
-          } catch (err) {
-            // As the {widget} macro refuses it: the others still register
-            console.error(
-              `spindle: widget "${def.name}" in passage "${passage.name}" was not registered: ${errorMessage(err)}`,
-            );
-          }
-        }
-      }
-    }
-  }
-
   // Reset action ID counters on every navigation (the passage remounts even
   // when its name is unchanged). Controls that stay mounted, e.g. in
   // StoryInterface, keep their IDs: allocation skips IDs still registered.

package/src/markup/render.tsx

@@ -52,7 +52,7 @@ export const InlineContext = createContext(false);
 /**
  * True while rendering inside an element whose content is not markdown: SVG
  * (whose namespace `<p>` wrappers would break) and the preformatted `<pre>`
- * and `<textarea>`, whose text (indentation, `#`, `*`, ...) is literal.
+ * `<textarea>` and `<style>`, whose text (indentation, `#`, `*`, ...) is literal.
  * Macro and widget bodies read it so their content stays literal too.
  */
 export const RawTextContext = createContext(false);
@@ -66,7 +66,7 @@ const SvgContext = createContext(false);
 const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
 
 /** Elements whose content is literal text, not markdown. */
-const PREFORMATTED_ELEMENTS = new Set(['pre', 'textarea']);
+const PREFORMATTED_ELEMENTS = new Set(['pre', 'textarea', 'style']);
 export const WidgetChildrenContext = createContext<ASTNode[] | null>(null);
 
 /**
@@ -348,7 +348,11 @@ function convertDomNode(
   return null;
 }
 
-/** Inline elements where block-level markdown (lists, headings) is invalid. */
+/**
+ * Elements whose content is phrasing content only, so block-level markdown
+ * (lists, headings, paragraphs) is invalid in them: inline elements, and
+ * block elements such as headings and buttons that only take inline children.
+ */
 const INLINE_ELEMENTS = new Set([
   'a',
   'abbr',
@@ -356,17 +360,27 @@ const INLINE_ELEMENTS = new Set([
   'bdi',
   'bdo',
   'br',
+  'button',
   'cite',
   'code',
   'data',
   'dfn',
   'em',
   'i',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
   'kbd',
   'label',
+  'legend',
   'mark',
   'meter',
+  'option',
   'output',
+  'p',
   'progress',
   'q',
   'rp',
@@ -378,6 +392,7 @@ const INLINE_ELEMENTS = new Set([
   'span',
   'strong',
   'sub',
+  'summary',
   'sup',
   'time',
   'u',
@@ -618,6 +633,15 @@ function resolveAttributeValue(
   return result.text;
 }
 
+/** The index of the summary element opening `nodes`, or -1 when none does. */
+function leadingSummaryIndex(nodes: ASTNode[]): number {
+  const at = nodes.findIndex((n) => n.type !== 'text' || n.value.trim() !== '');
+  const first = nodes[at];
+  return first?.type === 'html' && first.tag.toLowerCase() === 'summary'
+    ? at
+    : -1;
+}
+
 function HtmlNodeRenderer({ node }: { node: HtmlNode }) {
   const scope = useTextScope();
   const { nobr, locals, raw: inRaw, inline: parentInline } = useRenderOptions();
@@ -644,7 +668,22 @@ function HtmlNodeRenderer({ node }: { node: HtmlNode }) {
     if (inRaw || isRawRoot) {
       children = renderInlineNodes(node.children);
     } else {
-      children = renderNodes(node.children, { nobr, locals, inline: isInline });
+      // A details element's summary stays its direct child: it is rendered
+      // apart from the markdown of the rest of the content.
+      const summaryAt =
+        tag === 'details' ? leadingSummaryIndex(node.children) : -1;
+      const body = (nodes: ASTNode[]) =>
+        renderNodes(nodes, { nobr, locals, inline: isInline });
+      children =
+        summaryAt === -1 ? (
+          body(node.children)
+        ) : (
+          <>
+            {body(node.children.slice(0, summaryAt))}
+            {renderSingleNode(node.children[summaryAt]!)}
+            {body(node.children.slice(summaryAt + 1))}
+          </>
+        );
       if (isInline !== parentInline) {
         children = (
           <InlineContext.Provider value={isInline}>

package/src/saves/save-manager.ts

@@ -36,7 +36,16 @@ export function setSaveTitlePassage(content: string): void {
   saveTitlePassageContent = content;
 }
 
+/**
+ * The title of a save. The SaveTitle passage and title generators may draw
+ * random numbers; like the save hooks they must not advance the story's PRNG
+ * (see withoutDraws()).
+ */
 function generateTitle(payload: SavePayload): string {
+  return withoutDraws(() => generateTitleNow(payload));
+}
+
+function generateTitleNow(payload: SavePayload): string {
   // SaveTitle passage takes precedence
   if (saveTitlePassageContent) {
     try {

package/src/story-api.ts

@@ -23,6 +23,7 @@ import { getBackendType } from './saves/storage';
 import { registerClass } from './class-registry';
 import {
   frozenCopy,
+  readOnlyValue,
   getActiveMutationScope,
   mutateState,
 } from './execute-mutation';
@@ -286,7 +287,7 @@ function createStoryAPI(): StoryAPI {
       const value = key.includes('.')
         ? getByPath(namespace, key.split('.'))
         : ownValue(namespace, key);
-      return scope ? frozenCopy(value) : value;
+      return scope ? frozenCopy(value) : readOnlyValue(value);
     },
 
     set(nameOrVars: string | Record<string, unknown>, value?: unknown): void {

package/src/story-init.ts

@@ -1,6 +1,7 @@
 import { h, render } from 'preact';
 import { useStoryStore, recordStoryInitState, missingPassage } from './store';
 import { parseMarkup } from './markup/parse';
+import { registerWidgetDefinitions } from './widgets/register-widget-def';
 import { renderNodes } from './markup/render';
 import { setSaveTitlePassage } from './saves/save-manager';
 import { emit } from './event-emitter';
@@ -35,6 +36,9 @@ export function executeStoryInit() {
   const storyInit = state.storyData.passages.get('StoryInit');
   if (storyInit) {
     const ast = parseMarkup(storyInit.content);
+    // Its own widgets are usable from the passage itself: the macros render
+    // before the {widget} definitions' effects run.
+    registerWidgetDefinitions(ast, 'StoryInit');
 
     // Mount into a persistent hidden container. It stays mounted until the
     // next execution (restart) — this lets async effects (useEffect,

package/src/story-variables.ts

@@ -32,7 +32,13 @@ function tokensOf(text: string, textMode: boolean): Token[] {
   }
 }
 
-export type VarType = 'number' | 'string' | 'boolean' | 'array' | 'object';
+export type VarType =
+  | 'number'
+  | 'string'
+  | 'boolean'
+  | 'array'
+  | 'object'
+  | 'null';
 
 export interface FieldSchema {
   type: VarType;
@@ -66,7 +72,9 @@ function inferSchema(value: unknown): FieldSchema {
   if (Array.isArray(value)) {
     return { type: 'array' };
   }
-  if (value !== null && typeof value === 'object') {
+  // A default of null means "nothing yet"; the value may later be anything
+  if (value === null) return { type: 'null' };
+  if (typeof value === 'object') {
     const fields = new Map<string, FieldSchema>();
     for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
       fields.set(key, inferSchema(val));
@@ -156,6 +164,8 @@ function validateRef(
     // Arrays have built-in methods/properties (push, find, length, etc.)
     // so any field access on an array is allowed.
     if (current.type === 'array') return null;
+    // A null default may later hold a value of any shape
+    if (current.type === 'null') return null;
 
     // Primitives expose their wrapper's built-ins (length, toUpperCase,
     // toFixed, etc.). Keep validating past properties of primitive type.