Merge branch 'main' into nick/sd-2271-add-non-body-story-targeting-to-the-document-api

Author: harbournick

CLAUDE.md

@@ -67,6 +67,10 @@ tests/visual/        Visual regression tests (Playwright + R2 baselines)
 | Visual regression tests | `tests/visual/` (see its CLAUDE.md) |
 | Document API contract | `packages/document-api/src/contract/operation-definitions.ts` |
 | Adding a doc-api operation | See `packages/document-api/README.md` § "Adding a new operation" |
+| Theming (`createTheme()`) | `packages/superdoc/src/core/theme/create-theme.js` |
+| CSS variable defaults | `packages/superdoc/src/assets/styles/helpers/variables.css` |
+| Preset themes | `packages/superdoc/src/assets/styles/helpers/themes.css` |
+| Consumer-facing agent guide | `packages/superdoc/AGENTS.md` (ships with npm package) |
 
 ## Style Resolution Boundary
 
@@ -193,12 +197,15 @@ Pixel-level before/after comparison for documents that failed layout comparison.
 
 ## Brand & Design System
 
-Brand guidelines, voice, and design tokens live in `brand/`. Token values are defined in `packages/superdoc/src/assets/styles/tokens.css`.
+Brand guidelines, voice, and design tokens live in `brand/`.
+Token contract source is `packages/superdoc/src/assets/styles/helpers/variables.css` (`:root` defaults).
+Preset theme overrides are defined in `packages/superdoc/src/assets/styles/helpers/themes.css`.
 
 **When creating or modifying UI components:**
-- Use `--sd-*` CSS custom properties — never hardcode hex values. See `tokens.css` for all available variables.
-- Tokens follow three tiers: primitive (`--sd-color-blue-500`) → semantic (`--sd-action-primary`) → component (`--sd-comment-bg`). Components reference semantic or component-level variables.
-- Expose component-specific variables as `--sd-{component}-*` so consumers can customize via CSS.
-- Document component CSS variables in `apps/docs/ui-components/` (Mintlify docs).
+- Use `--sd-*` CSS custom properties — never hardcode hex values.
+- Treat `variables.css` as the canonical token contract; add new tokens there.
+- Keep preset themes in `themes.css` (`.sd-theme-*`) and override only the tokens that need theme-specific values.
+- Tokens are organized by layers: primitive (`--sd-color-blue-500`) → UI/document tokens (`--sd-ui-*`, `--sd-comments-*`, etc.) → component usage.
+- Expose UI component-specific variables as `--sd-ui-{component}-*` so consumers can customize via CSS.
 
 **When writing copy or content:** see `brand/brand-guidelines.md` for voice, tone, and the dual-register pattern (developer vs. leader). Product name is always **SuperDoc** (capital S, capital D).

apps/cli/scripts/export-sdk-contract.ts

@@ -98,6 +98,7 @@ function buildSdkContract() {
         if (p.flag && p.flag !== p.name) spec.flag = p.flag;
         if (p.required) spec.required = true;
         if (p.schema) spec.schema = p.schema;
+        if (p.description) spec.description = p.description;
         if (p.agentVisible === false) spec.agentVisible = false;
         return spec;
       }),

apps/cli/src/__tests__/conformance/scenarios.ts

@@ -2955,7 +2955,7 @@ export const SUCCESS_SCENARIOS = {
     '--destination-json',
     JSON.stringify({ kind: 'documentEnd' }),
   ]),
-  'doc.tables.split': tableMutationScenario('tables.split', ['--at-row-index', '1']),
+  'doc.tables.split': tableMutationScenario('tables.split', ['--row-index', '1']),
   'doc.tables.convertToText': tableMutationScenario('tables.convertToText', ['--delimiter', 'tab']),
   'doc.tables.setLayout': tableMutationScenario('tables.setLayout', ['--alignment', 'center']),
   'doc.tables.insertRow': tableMutationScenario('tables.insertRow', ['--row-index', '0', '--position', 'below']),

apps/cli/src/__tests__/lib/validate-type-spec.test.ts

@@ -7,6 +7,7 @@ describe('validateValueAgainstTypeSpec – oneOf const enumeration', () => {
   const schema: CliTypeSpec = {
     oneOf: [
       { const: 'headerRow' },
+      { const: 'lastRow' },
       { const: 'totalRow' },
       { const: 'firstColumn' },
       { const: 'lastColumn' },
@@ -20,16 +21,24 @@ describe('validateValueAgainstTypeSpec – oneOf const enumeration', () => {
     expect(() => validateValueAgainstTypeSpec('bandedColumns', schema, 'flag')).not.toThrow();
   });
 
+  test('accepts lastRow as a valid flag', () => {
+    expect(() => validateValueAgainstTypeSpec('lastRow', schema, 'flag')).not.toThrow();
+  });
+
+  test('accepts totalRow as a deprecated alias', () => {
+    expect(() => validateValueAgainstTypeSpec('totalRow', schema, 'flag')).not.toThrow();
+  });
+
   test('rejects an invalid value and lists all allowed values', () => {
     try {
-      validateValueAgainstTypeSpec('lastRow', schema, 'tables set-style-option:flag');
+      validateValueAgainstTypeSpec('bogusFlag', schema, 'tables set-style-option:flag');
       throw new Error('Expected CliError to be thrown');
     } catch (error) {
       expect(error).toBeInstanceOf(CliError);
       const cliError = error as CliError;
       expect(cliError.code).toBe('VALIDATION_ERROR');
       expect(cliError.message).toBe(
-        'tables set-style-option:flag must be one of: headerRow, totalRow, firstColumn, lastColumn, bandedRows, bandedColumns.',
+        'tables set-style-option:flag must be one of: headerRow, lastRow, totalRow, firstColumn, lastColumn, bandedRows, bandedColumns.',
       );
     }
   });
@@ -41,7 +50,7 @@ describe('validateValueAgainstTypeSpec – oneOf const enumeration', () => {
     } catch (error) {
       const cliError = error as CliError;
       const details = cliError.details as { errors: string[] };
-      expect(details.errors).toBeArrayOfSize(6);
+      expect(details.errors).toBeArrayOfSize(7);
     }
   });
 });