cursedbelt 5.91.0 → 5.92.0

package/dist/styles-areas/wizard.css

@@ -18,19 +18,14 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 42 candidate(s).
+ * 25 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
  * import closures rather than a hand-written list, is scripts/styleAreas.ts.
  */
-@source inline("[&_svg]:size-3 border-field-error collapse data-[ending-style]:opacity-0");
-@source inline("data-[ending-style]:scale-95 data-[highlighted]:bg-accent/10");
-@source inline("data-[highlighted]:text-accent-strong data-[starting-style]:opacity-0");
-@source inline("data-[starting-style]:scale-95 disabled:bg-transparent disabled:opacity-100 duration-100");
-@source inline("focus-visible:ring-field-ring/40 focus-within:border-field-ring focus-within:ring-2");
-@source inline("focus-within:ring-field-ring/30 h-105 has-[[aria-invalid=true]]:border-field-error");
-@source inline("hover:border-field-ring hover:text-warning max-h-64 min-h-20 min-w-24");
-@source inline("min-w-[var(--anchor-width)] mr-1.5 mr-2 pl-1.5 pl-2 pr-1 pr-16 pr-3 resize-none resize-y");
-@source inline("ring-field-error/30 self-stretch size-7 sm:inline text-field-placeholder text-xl");
-@source inline("transition-[transform,opacity] w-36 w-88");
+@source inline("border-field-error collapse disabled:bg-transparent disabled:opacity-100");
+@source inline("focus-visible:ring-field-ring/40 h-105 has-[[aria-invalid=true]]:border-field-error");
+@source inline("hover:border-field-ring hover:text-warning min-h-20 mr-1.5 mr-2 pl-1.5 pr-16 pr-3 resize-none");
+@source inline("resize-y ring-field-error/30 self-stretch size-7 sm:inline text-field-placeholder text-xl w-36");
+@source inline("w-88");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "5.91.0",
+	"version": "5.92.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The React design system of the cursedbelt split — components, styles, theme. cursedbelt-core below it; server tier in cursedbelt-server.",
@@ -528,6 +528,12 @@
 			"source": "./src/react/components/Modal.tsx",
 			"import": "./dist/react/components/Modal.js"
 		},
+		"./react/autocomplete": {
+			"types": "./dist/react/components/Autocomplete.d.ts",
+			"bun": "./src/react/components/Autocomplete.tsx",
+			"source": "./src/react/components/Autocomplete.tsx",
+			"import": "./dist/react/components/Autocomplete.js"
+		},
 		"./react/multi-select-field": {
 			"types": "./dist/react/components/MultiSelectField.d.ts",
 			"bun": "./src/react/components/MultiSelectField.tsx",

package/scripts/guardrails-baseline.json

@@ -24,7 +24,7 @@
     "no-inline-style": 73,
     "no-arbitrary-length": 0,
     "opt-out-count": 272,
-    "opt-out-needs-cause": 254
+    "opt-out-needs-cause": 253
   },
   "cursedshell": {
     "no-raw-action-button": 0,

package/scripts/guardrailsEnforce.spec.ts

@@ -1063,6 +1063,19 @@ describe('no-native-select — the OS draws its list (owner, 2026-10-10)', () =>
     expect(check('no-native-select', `<selection-bar />`)).toHaveLength(0);
   });
 
+  // forge task 3602, the owner 2026-10-23: *"When I click the add a tag dropdown, the dropdown does
+  // not look styled … I was in dark mode and it popped up light."* That was an `<input list>`.
+  test('a <datalist> is the same OS list, and counts too (forge task 3602)', () => {
+    const source = `<input list="known-tags" value={tag} onChange={(e) => setTag(e.target.value)} />
+    <datalist id="known-tags">
+      {tags.map((t) => <option key={t} value={t} />)}
+    </datalist>`;
+    expect(check('no-native-select', source)).toHaveLength(1);
+    expect(check('no-native-select', `<datalist id={\`ft-record-\${category}\`}>`)).toHaveLength(1);
+    expect(check('no-native-select', `// was a <datalist> until 3602\n<AutocompleteField suggestions={tags} />`)).toHaveLength(0);
+    expect(check('no-native-select', `<datalistish />`)).toHaveLength(0);
+  });
+
   test('the styled controls, and a comment that names it, are not one', () => {
     expect(check('no-native-select', `<SelectField value={sort} options={SORTS} />`)).toHaveLength(0);
     expect(check('no-native-select', `// was a <NativeSelect> until 2026-10-10\n<PropertyPicker name="Type" />`)).toHaveLength(0);

package/scripts/guardrailsEnforce.ts

@@ -2092,7 +2092,9 @@ const noSelectAsActionMenu: Rule = {
 // even the kit's frame (forge task 3097: desk had eight under `no-raw-inputs`, which no count of
 // NativeSelect could see) — in its two-sided ratchet, so the number only falls:
 // `SelectField` / `ComboboxField` for a field, `PropertyPicker` for a record's property pill,
-// `ChoiceMenu` to choose-and-act. A use that is genuinely right — a form on a phone where the OS
+// `ChoiceMenu` to choose-and-act. A `<datalist>` counts too (forge task 3602, the owner 2026-10-23:
+// a tag field's suggestions *"popped up light"* in dark mode) — `<input list>`'s dropdown is the
+// same OS list; `AutocompleteField` or `TagsInput` suggest in the page. A use that is genuinely right — a form on a phone where the OS
 // wheel IS the better control — says so on the line above:
 // `// guardrails-ignore no-native-select: <why>`.
 const NATIVE_SELECT_IGNORE_RE = /guardrails-ignore\s+no-native-select\s*:/;
@@ -2100,7 +2102,7 @@ const NATIVE_SELECT_IGNORE_RE = /guardrails-ignore\s+no-native-select\s*:/;
 const noNativeSelect: Rule = {
 	name: "no-native-select",
 	description:
-		"Owner, 2026-10-10: unstyled dropdowns break the app's cohesiveness. A `NativeSelect`'s (or a raw `<select>`'s) list is drawn by the OS, outside the page, where no stylesheet reaches it. Use `SelectField` / `ComboboxField` for a form field, `PropertyPicker` for a record's property (Type, Folder, Tags), or `ChoiceMenu` to choose-and-act. Where the OS picker is the better control, say why on the line above: `// guardrails-ignore no-native-select: <why>`.",
+		"Owner, 2026-10-10: unstyled dropdowns break the app's cohesiveness. A `NativeSelect`'s (or a raw `<select>`'s, or a `<datalist>`'s) list is drawn by the OS, outside the page, where no stylesheet reaches it. Use `SelectField` / `ComboboxField` for a form field, `AutocompleteField` / `TagsInput` for suggestions as you type, `PropertyPicker` for a record's property (Type, Folder, Tags), or `ChoiceMenu` to choose-and-act. Where the OS picker is the better control, say why on the line above: `// guardrails-ignore no-native-select: <why>`.",
 	check(filePath, source) {
 		const unix = filePath.replace(/\\/g, "/");
 		// The kit is held to its own law (forge task 3063: its DataTable filter builder and
@@ -2112,7 +2114,7 @@ const noNativeSelect: Rule = {
 		const scannable = blankComments(source);
 		const lines = source.split("\n");
 		const out: Violation[] = [];
-		for (const match of scannable.matchAll(/<(?:NativeSelect|select)\b/g)) {
+		for (const match of scannable.matchAll(/<(?:NativeSelect|select|datalist)\b/g)) {
 			const line = lineOf(source, match.index ?? 0);
 			if (NATIVE_SELECT_IGNORE_RE.test(lines[line - 1] ?? "") || NATIVE_SELECT_IGNORE_RE.test(blockAbove(lines, line))) continue;
 			out.push({ file: filePath, line, snippet: lines[line - 1]?.trim() ?? "" });

package/scripts/styleAreas.ts

@@ -181,6 +181,9 @@ export const AREAS: readonly Area[] = [
 			'components/IconButton.tsx',
 			'components/InfoHint.tsx',
 			'components/InfoHintImpl.tsx',
+			// TagsInput `import()`s it (forge task 3614) from seven areas' closures (lazyImportFault) — named
+			// here once, so whichever area reaches TagsInput, its suggestion list is styled.
+			'components/TagsInputSuggesting.tsx',
 			'components/Input.tsx',
 			'components/ListPanel.tsx',
 			'components/Menu.tsx',

package/src/react/activity-bar/activityBar.css

@@ -264,6 +264,11 @@
 	.cbab-slot {
 		inline-size: 44px;
 		block-size: 44px;
+	}
+
+	/* 12px centers the rail's OWN 20px glyph. A slot holds the consumer's control, which
+	   `max-inline-size: 100%` would squeeze to that 20px — it gets the whole 44 instead. */
+	.cbab-btn {
 		padding-inline: 12px;
 	}
 }

package/src/react/components/Autocomplete.spec.tsx

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, mock, test } from 'bun:test';
 import { act, cleanup, fireEvent, render, waitFor } from '@testing-library/react';
-import { useState } from 'react';
+import { createRef, useState } from 'react';
 import { AutocompleteField } from './Autocomplete.js';
 
 afterEach(cleanup);
@@ -79,4 +79,58 @@ describe('AutocompleteField', () => {
     // Suggestions should be visible in the popup (portaled to document.body)
     expect(getByText('Apple')).not.toBeNull();
   });
+
+  // 🔴 Seen on music-stage, 2026-10-23: "zz" still offered every folder — the list drew the whole
+  // static array, never Base UI's filtered one (forge task 3602).
+  test('static suggestions narrow to what contains the typed text, in any case', () => {
+    const { container, queryByText } = render(<Controlled initial='AP' />);
+    const input = container.querySelector('input') as HTMLInputElement;
+    act(() => {
+      fireEvent.keyDown(input, { key: 'ArrowDown' });
+    });
+    expect(queryByText('Apple')).not.toBeNull();
+    expect(queryByText('Apricot')).not.toBeNull();
+    expect(queryByText('Banana')).toBeNull();
+    expect(queryByText('Cherry')).toBeNull();
+  });
+
+  test('inputRef is the input, so a form can focus the field it names as missing', () => {
+    const ref = createRef<HTMLInputElement>();
+    const { container } = render(<AutocompleteField inputRef={ref} suggestions={SUGGESTIONS} />);
+    expect(ref.current).toBe(container.querySelector('input'));
+  });
+
+  test('a field that is more than its query brings its own match', () => {
+    // A comma list: each suggestion is the whole next value, and only the LAST entry is the query.
+    const last = (text: string) => text.slice(text.lastIndexOf(',') + 1).trim().toLowerCase();
+    const { container, queryByText } = render(
+      <AutocompleteField
+        value='rock, an'
+        suggestions={['rock, trance', 'rock, ambient', 'rock, jazz']}
+        filter={(item, query) => last(item).includes(last(query))}
+      />,
+    );
+    act(() => {
+      fireEvent.keyDown(container.querySelector('input') as HTMLInputElement, { key: 'ArrowDown' });
+    });
+    expect(queryByText('rock, trance')).not.toBeNull();
+    expect(queryByText('rock, ambient')).toBeNull();
+    expect(queryByText('rock, jazz')).toBeNull();
+  });
+
+  test('loadSuggestions answers are drawn as given — the loader already searched', async () => {
+    const loadSuggestions = mock(async () => ['Zebra', 'Yak']);
+    function Async() {
+      const [value, setValue] = useState('qq');
+      return <AutocompleteField value={value} onChange={setValue} loadSuggestions={loadSuggestions} />;
+    }
+    const { container, queryByText } = render(<Async />);
+    await waitFor(() => expect(loadSuggestions).toHaveBeenCalled(), { timeout: 1000 });
+    const input = container.querySelector('input') as HTMLInputElement;
+    await act(async () => {
+      fireEvent.keyDown(input, { key: 'ArrowDown' });
+    });
+    await waitFor(() => expect(queryByText('Zebra')).not.toBeNull(), { timeout: 1000 });
+    expect(queryByText('Yak')).not.toBeNull();
+  });
 });

package/src/react/components/Autocomplete.tsx

@@ -2,12 +2,11 @@
 
 import { Autocomplete } from '@base-ui/react/autocomplete';
 import { ChevronDown, Loader2 } from 'lucide-react';
-import { type InputHTMLAttributes, type ReactNode, useCallback, useEffect, useState } from 'react';
+import { type InputHTMLAttributes, type ReactNode, type Ref, useCallback, useEffect, useState } from 'react';
 import { useDebouncedCallback } from '../hooks/useDebouncedCallback.js';
 import { cn } from '../lib/cn.js';
 import { type ControlSize, fieldControlClass } from '../lib/field.js';
-import { FLOATING_COLLISION_PADDING,
-  FLOATING_CONTENT_BASE, FLOATING_ITEM_BASE } from '../lib/floatingStyles.js';
+import { SuggestionList } from './suggestionList.js';
 
 export interface AutocompleteProps<S = string>
   extends Omit<
@@ -30,6 +29,13 @@ export interface AutocompleteProps<S = string>
   onBlur?: () => void;
   /** Static suggestion items shown in the dropdown. */
   suggestions?: S[];
+  /**
+   * Whether a static suggestion matches what is typed. Default: its text CONTAINS the typed text,
+   * any case (Base UI's own match). A field whose value is more than the query — a comma list
+   * where each suggestion completes the LAST entry — passes its own. `null` shows them as given.
+   * Never applied to {@link loadSuggestions}: the loader's answer already is the search.
+   */
+  filter?: ((item: S, query: string) => boolean) | null;
   /** Async fetch — called on every keystroke (debounced 250 ms).
    *  When provided, replaces the static `suggestions`. */
   loadSuggestions?: (query: string) => Promise<S[]>;
@@ -54,6 +60,8 @@ export interface AutocompleteProps<S = string>
   /** Height on the shared control-height scale (`--control-h-*`, task cbux-41).
    *  Default `md`. */
   size?: ControlSize;
+  /** The input element — to focus it from a form that names what is missing. */
+  inputRef?: Ref<HTMLInputElement>;
 }
 
 const DEBOUNCE_MS = 250;
@@ -74,6 +82,7 @@ export function AutocompleteField<S = string>({
   onChange,
   onBlur,
   suggestions = [],
+  filter,
   loadSuggestions,
   itemToString = (item) => String(item),
   renderSuggestion,
@@ -85,6 +94,7 @@ export function AutocompleteField<S = string>({
   'aria-describedby': ariaDescribedBy,
   className,
   size = 'md',
+  inputRef,
   ...rest
 }: AutocompleteProps<S>) {
   const isAsync = Boolean(loadSuggestions);
@@ -127,11 +137,15 @@ export function AutocompleteField<S = string>({
       itemToStringValue={itemToString}
       disabled={disabled}
       mode='list'
+      // Static suggestions narrow to what is typed (by default Base UI's own match: contains, any
+      // case, accents folded). A loader's answer is already the search — drawn as it came.
+      filter={isAsync ? null : filter}
       autoHighlight={false}
     >
       <Autocomplete.InputGroup className='relative flex items-center'>
         <Autocomplete.Input
           {...rest}
+          ref={inputRef}
           id={id}
           name={name}
           aria-invalid={ariaInvalid}
@@ -153,46 +167,7 @@ export function AutocompleteField<S = string>({
         </span>
       </Autocomplete.InputGroup>
 
-      <Autocomplete.Portal>
-        {/* 🔴 The z-index goes on the POSITIONER, not only the popup. Base UI's positioner is
-            the element that is `position: absolute` (with a transform); the popup inside it is
-            `position: static`, so the popup's own `z-[var(--z-popover)]` does nothing and the
-            list painted UNDER any sibling with a z-index — measured 2026-09-22 in the
-            binary-server inspector, a sticky table header (z-index 1) covering the second option
-            of an open MultiSelectField. */}
-        <Autocomplete.Positioner
-          sideOffset={4}
-          collisionPadding={FLOATING_COLLISION_PADDING}
-          className='z-[var(--z-popover)]'
-        >
-          <Autocomplete.Popup
-            className={cn(
-              FLOATING_CONTENT_BASE,
-              // guardrails-ignore no-raw-overflow: floating popover panel outside the page's ScrollArea, height-capped by max-h-64 — no keyboard-inset concern.
-              'max-h-64 min-w-[var(--anchor-width)] overflow-y-auto p-0 py-1',
-              'transition-[transform,opacity] duration-100',
-              'data-[starting-style]:scale-95 data-[starting-style]:opacity-0',
-              'data-[ending-style]:scale-95 data-[ending-style]:opacity-0',
-            )}
-          >
-            <Autocomplete.List>
-              {activeSuggestions.map((s, index) => (
-                <Autocomplete.Item
-                  key={itemToString(s)}
-                  value={s}
-                  index={index}
-                  className={cn(
-                    FLOATING_ITEM_BASE,
-                    'data-[highlighted]:bg-accent/10 data-[highlighted]:text-accent-strong',
-                  )}
-                >
-                  {renderSuggestion ? renderSuggestion(s) : itemToString(s)}
-                </Autocomplete.Item>
-              ))}
-            </Autocomplete.List>
-          </Autocomplete.Popup>
-        </Autocomplete.Positioner>
-      </Autocomplete.Portal>
+      <SuggestionList itemToString={itemToString} renderSuggestion={renderSuggestion} />
     </Autocomplete.Root>
   );
 }

package/src/react/components/FileDropZone.tsx

@@ -2,6 +2,7 @@ import { Upload, X } from 'lucide-react';
 import { type DragEvent, type ReactNode, useId, useRef, useState } from 'react';
 import { cn } from '../lib/cn.js';
 import { Button } from './Button.js';
+import { isHiddenName, matchesAccept, walkDrop } from './dropTransfer.js';
 import { Input } from './Input.js';
 
 export interface FileDropZoneProps {
@@ -51,102 +52,30 @@ export interface FileDropZoneProps {
   className?: string;
 }
 
-/** The slice of the File and Directory Entries API a drop needs — every browser ships it. */
-interface DropEntry {
-  isFile: boolean;
-  isDirectory: boolean;
-  name: string;
-  file?: (ok: (file: File) => void, fail: (error: unknown) => void) => void;
-  createReader?: () => {
-    readEntries: (ok: (entries: DropEntry[]) => void, fail: (error: unknown) => void) => void;
-  };
-}
-
-/** What a folder can hold before walking it stops — a drop, not a disk scan. */
-const MAX_FOLDER_FILES = 5000;
-
-const isHidden = (name: string) => name.startsWith('.');
-
-/**
- * Every file under `entry`, depth-first. A directory's reader answers in batches until empty.
- *
- * Each file carries its path from the dropped folder in `webkitRelativePath` (`Album/CD1/01.mp3`),
- * exactly as a folder PICKER's files do natively — so an app reading provenance (music defaults
- * its "where these came from" field to the top folder) gets the same answer from both gestures.
- * A drop leaves it `''` otherwise, and that difference is what kept music on its own walk.
- */
-async function filesUnder(entry: DropEntry, out: File[], prefix = ''): Promise<void> {
-  if (out.length >= MAX_FOLDER_FILES || isHidden(entry.name)) return;
-  if (entry.isFile && entry.file) {
-    const read = entry.file.bind(entry);
-    const file = await new Promise<File>((ok, fail) => read(ok, fail));
-    Object.defineProperty(file, 'webkitRelativePath', { value: `${prefix}${file.name}`, configurable: true });
-    out.push(file);
-    return;
-  }
-  if (!entry.isDirectory || !entry.createReader) return;
-  const reader = entry.createReader();
-  while (out.length < MAX_FOLDER_FILES) {
-    const batch = await new Promise<DropEntry[]>((ok, fail) => reader.readEntries(ok, fail));
-    if (batch.length === 0) return;
-    for (const child of batch) await filesUnder(child, out, `${prefix}${entry.name}/`);
-  }
-}
-
 /**
  * A drop's files, with every dropped FOLDER replaced by the accepted files inside it — see the
  * FOLDER section above. `null` when nothing in the drop is a folder, so the ordinary path stays
- * exactly `dataTransfer.files`.
- *
- * 🔴 The entries are taken SYNCHRONOUSLY, before the first `await`: a browser empties the
- * `DataTransfer` once the drop event returns.
+ * exactly `dataTransfer.files`. The walk itself is {@link walkDrop}, shared with every app's own
+ * drop target through {@link filesFromDataTransfer}.
  */
 function folderAwareDrop(
   transfer: DataTransfer,
   accept: string | undefined,
 ): Promise<{ loose: File[]; fromFolders: File[]; emptyFolders: File[] }> | null {
-  const items = transfer.items ? [...transfer.items] : [];
-  const entries = items.map((item) =>
-    item.kind === 'file' && typeof item.webkitGetAsEntry === 'function'
-      ? (item.webkitGetAsEntry() as DropEntry | null)
-      : null,
-  );
-  if (!entries.some((entry) => entry?.isDirectory)) return null;
-  const looseFiles = [...transfer.files];
-  return (async () => {
-    const loose: File[] = [];
+  const walking = walkDrop(transfer);
+  if (!walking) return null;
+  return walking.then(({ loose, folders }) => {
     const fromFolders: File[] = [];
     const emptyFolders: File[] = [];
-    for (const [i, entry] of entries.entries()) {
-      if (!entry?.isDirectory) {
-        const file = looseFiles[i] ?? (entry ? await new Promise<File | null>((ok) => entry.file?.(ok, () => ok(null))) : null);
-        if (file) loose.push(file);
-        continue;
-      }
-      const inside: File[] = [];
-      try {
-        await filesUnder(entry, inside);
-      } catch {
-        // An unreadable folder yields what was read before the error — and, if that is nothing, a refusal below.
-      }
-      const kept = inside.filter((f) => matchesAccept(f, accept));
+    for (const folder of folders) {
+      // A folder that yields nothing acceptable is a refusal under its own name, never silence.
+      const kept = folder.files.filter((f) => matchesAccept(f, accept));
       if (kept.length > 0) fromFolders.push(...kept);
-      else emptyFolders.push(new File([], entry.name));
+      else emptyFolders.push(new File([], folder.name));
     }
     return { loose, fromFolders, emptyFolders };
-  })();
-}
-
-const matchesAccept = (file: File, accept?: string): boolean => {
-  if (!accept) return true;
-  return accept.split(',').some((raw) => {
-    const rule = raw.trim().toLowerCase();
-    if (!rule) return false;
-    if (rule.startsWith('.')) return file.name.toLowerCase().endsWith(rule);
-    if (rule.endsWith('/*')) return file.type.toLowerCase().startsWith(rule.slice(0, -1));
-    return file.type.toLowerCase() === rule;
   });
-};
+}
 
 /**
  * A folder PICKER's files, judged the way a dropped folder's are: what `accept` turns away is
@@ -156,7 +85,7 @@ const matchesAccept = (file: File, accept?: string): boolean => {
  */
 function folderPick(list: FileList | null, accept: string | undefined): { fromFolders: File[]; emptyFolders: File[] } {
   const all = list ? [...list] : [];
-  const kept = all.filter((f) => !f.webkitRelativePath.split('/').some(isHidden) && matchesAccept(f, accept));
+  const kept = all.filter((f) => !f.webkitRelativePath.split('/').some(isHiddenName) && matchesAccept(f, accept));
   if (kept.length > 0 || all.length === 0) return { fromFolders: kept, emptyFolders: [] };
   const name = all[0]?.webkitRelativePath.split('/')[0] || 'That folder';
   return { fromFolders: [], emptyFolders: [new File([], name)] };

package/src/react/components/TagsInput.spec.tsx

@@ -1,7 +1,9 @@
-import { afterEach, describe, expect, test } from 'bun:test';
-import { cleanup, fireEvent, render } from '@testing-library/react';
+import { afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { act, cleanup, fireEvent, render, waitFor } from '@testing-library/react';
 import { useState } from 'react';
-import { TagsInput } from './TagsInput.js';
+import { preloadSuggestingTagsInput, TagsInput } from './TagsInput.js';
 
 afterEach(cleanup);
 
@@ -80,17 +82,76 @@ describe('TagsInput', () => {
   });
 });
 
+/**
+ * 🔴 Never a `<datalist>` (forge task 3602). The owner, 2026-10-23: *"the dropdown does not look
+ * styled … I was in dark mode and it popped up light"* — the browser draws a datalist outside the
+ * page. The list is the kit's own (Base UI Autocomplete, portaled), carrying the popover tokens.
+ */
+/**
+ * A BYTE contract as much as a behavioral one (forge task 3614): the suggesting field is Base UI's
+ * Autocomplete, ~38 kB gzip, and 5.92.0 rooted every TagsInput in it — station's FolderSizesView,
+ * whose rules fields suggest nothing, went 7.15 → 44.32 kB gzip. A field without `suggestions`
+ * must not carry that engine; one with them fetches it, and loses nothing typed meanwhile.
+ *
+ * 🔴 These run BEFORE the `suggestions` block preloads the engine, so the first render here is
+ * the plain field the hand-over starts from.
+ */
+describe('the suggesting field is loaded only when asked for', () => {
+  test('TagsInput.tsx imports no Base UI, and reaches the suggesting field dynamically', () => {
+    const src = readFileSync(join(import.meta.dir, 'TagsInput.tsx'), 'utf8');
+    expect(src).not.toMatch(/from\s*['"]@base-ui\//);
+    expect(src).not.toMatch(/from\s*['"]\.\/(TagsInputSuggesting|suggestionList)(\.js)?['"]/);
+    expect(src).toContain("import('./TagsInputSuggesting.js')");
+  });
+
+  test('a draft typed and the focus held before the engine arrives are still there after', async () => {
+    const { container } = render(
+      <TagsInput value={[]} onChange={() => undefined} suggestions={['banking', 'tax']} />,
+    );
+    const plain = container.querySelector('input') as HTMLInputElement;
+    expect(plain.getAttribute('role'), 'the engine was already loaded — this test must run first').toBeNull();
+    act(() => plain.focus());
+    fireEvent.change(plain, { target: { value: 'ba' } });
+    // Where the focus is in the commit that swaps the inputs, not some polls later: a mutation
+    // record is a microtask after that commit, before any passive effect (a later task), so a
+    // hand-over in `useEffect` reads <body> here every time, not only under a loaded gate.
+    let focusAtSwap: Element | null | undefined;
+    const swap = new MutationObserver(() => {
+      if (focusAtSwap === undefined && container.querySelector('input[role="combobox"]')) {
+        focusAtSwap = document.activeElement;
+      }
+    });
+    swap.observe(container, { childList: true, subtree: true, attributes: true });
+    await waitFor(() => expect(container.querySelector('input')?.getAttribute('role')).toBe('combobox'));
+    swap.disconnect();
+    const suggesting = container.querySelector('input') as HTMLInputElement;
+    expect(suggesting.value).toBe('ba');
+    expect(focusAtSwap).toBe(suggesting);
+    expect(document.activeElement).toBe(suggesting);
+  });
+});
+
 describe('suggestions', () => {
-  test('offers a datalist of suggestions, minus what is already committed', () => {
+  // Every case below draws the list, so the engine is in hand before the first render.
+  beforeAll(() => preloadSuggestingTagsInput());
+
+  const openList = (input: HTMLInputElement) =>
+    act(() => {
+      fireEvent.keyDown(input, { key: 'ArrowDown' });
+    });
+  const offeredNow = () => [...document.querySelectorAll('[role="option"]')].map((o) => o.textContent);
+
+  test('drawn in the page with the kit tokens, never a datalist — minus what is already committed', () => {
     const { container } = render(
       <TagsInput value={['work']} onChange={() => undefined} suggestions={['work', 'bank']} />,
     );
     const input = container.querySelector('input') as HTMLInputElement;
-    const list = container.querySelector('datalist') as HTMLDataListElement;
-    expect(list).not.toBeNull();
-    expect(input.getAttribute('list')).toBe(list.id);
-    const offered = [...list.querySelectorAll('option')].map((o) => o.getAttribute('value'));
-    expect(offered).toEqual(['bank']);
+    expect(document.querySelector('datalist')).toBeNull();
+    expect(input.getAttribute('list')).toBeNull();
+    openList(input);
+    expect(offeredNow()).toEqual(['bank']);
+    const popup = document.querySelector('[role="option"]')?.closest('.bg-popover');
+    expect(popup, 'the list does not carry the popover tokens').not.toBeNull();
   });
 
   test('🔴 suppression is case-insensitive — "Bank" committed hides the suggestion "bank"', () => {
@@ -100,16 +161,70 @@ describe('suggestions', () => {
     const { container } = render(
       <TagsInput value={['Bank']} onChange={() => undefined} suggestions={['bank', 'tax']} />,
     );
-    const offered = [...container.querySelectorAll('datalist option')].map((o) =>
-      o.getAttribute('value'),
+    openList(container.querySelector('input') as HTMLInputElement);
+    expect(offeredNow()).toEqual(['tax']);
+  });
+
+  test('narrows to what is typed, in any case', () => {
+    const { container } = render(
+      <TagsInput value={[]} onChange={() => undefined} suggestions={['Banking', 'tax', 'bank']} />,
     );
-    expect(offered).toEqual(['tax']);
+    const input = container.querySelector('input') as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'BAN' } });
+    openList(input);
+    expect(offeredNow()).toEqual(['Banking', 'bank']);
+  });
+
+  test('picking a suggestion commits it as a tag — not the half-typed draft', () => {
+    function WithSuggestions() {
+      const [value, setValue] = useState<string[]>([]);
+      return (
+        <div>
+          <TagsInput value={value} onChange={setValue} suggestions={['banking', 'tax']} />
+          <output data-json>{JSON.stringify(value)}</output>
+        </div>
+      );
+    }
+    const { container } = render(<WithSuggestions />);
+    const input = container.querySelector('input') as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'ba' } });
+    openList(input);
+    act(() => {
+      fireEvent.click(document.querySelector('[role="option"]') as HTMLElement);
+    });
+    expect(json(container)).toEqual(['banking']);
+    expect(input.value).toBe('');
+  });
+
+  test('Enter on a highlighted suggestion commits the suggestion', () => {
+    function WithSuggestions() {
+      const [value, setValue] = useState<string[]>([]);
+      return (
+        <div>
+          <TagsInput value={value} onChange={setValue} suggestions={['banking', 'tax']} />
+          <output data-json>{JSON.stringify(value)}</output>
+        </div>
+      );
+    }
+    const { container } = render(<WithSuggestions />);
+    const input = container.querySelector('input') as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'ba' } });
+    openList(input);
+    act(() => {
+      fireEvent.keyDown(input, { key: 'ArrowDown' });
+    });
+    act(() => {
+      fireEvent.keyDown(input, { key: 'Enter' });
+    });
+    expect(json(container)).toEqual(['banking']);
   });
 
-  test('no suggestions → no datalist and no dangling list attribute', () => {
+  test('no suggestions → no list and no dangling list attribute', () => {
     const { container } = render(<TagsInput value={[]} onChange={() => undefined} />);
-    expect(container.querySelector('datalist')).toBeNull();
+    expect(document.querySelector('datalist')).toBeNull();
     const input = container.querySelector('input') as HTMLInputElement;
     expect(input.getAttribute('list')).toBeNull();
+    openList(input);
+    expect(offeredNow()).toEqual([]);
   });
 });