@nowline/config 0.8.6 → 0.9.0

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export { type LoadConfigOptions, type LoadConfigResult, loadConfig, mergeConfig, type NowlineRc, parseConfig, } from './load-config.js';
+export { type LoadConfigOptions, type LoadConfigResult, loadConfig, type NowlineRc, parseConfig, } from './load-config.js';
+export { ASSET_ROOT_SPEC, MIN_WIDTH, type NowPolicy, type OptionError, type OptionKeyOf, type OptionLayer, type OptionParse, type OptionSource, type OptionSpec, type OptionSpecTable, type OptionValues, rcLayer, resolveOptions, resolveSurfaceOptions, SURFACE_OPTION_SPECS, SURFACE_RC_KEYS, type SurfaceOptionKey, type SurfaceOptionSpecs, type SurfaceOptions, type SurfaceRcValues, } from './surface-options.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,UAAU,EACV,WAAW,EACX,KAAK,SAAS,EACd,WAAW,GACd,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,UAAU,EACV,KAAK,SAAS,EACd,WAAW,GACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACH,eAAe,EACf,SAAS,EACT,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,OAAO,EACP,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,eAAe,GACvB,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
-export { loadConfig, mergeConfig, parseConfig, } from './load-config.js';
+export { loadConfig, parseConfig, } from './load-config.js';
+export { ASSET_ROOT_SPEC, MIN_WIDTH, rcLayer, resolveOptions, resolveSurfaceOptions, SURFACE_OPTION_SPECS, SURFACE_RC_KEYS, } from './surface-options.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGH,UAAU,EACV,WAAW,EAEX,WAAW,GACd,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGH,UAAU,EAEV,WAAW,GACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACH,eAAe,EACf,SAAS,EAUT,OAAO,EACP,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,GAKlB,MAAM,sBAAsB,CAAC"}

package/dist/load-config.d.ts

@@ -1,15 +1,14 @@
+import type { SurfaceRcValues } from './surface-options.js';
 /**
- * Shape of the `.nowlinerc` file consumed by the CLI today and (post-m3d)
- * by the VS Code/Cursor extension. Keys are intentionally optional — the
- * file is sparse and any key may be absent.
+ * Shape of the `.nowlinerc` file consumed by the CLI and the VS Code/Cursor
+ * extension. Keys are intentionally optional — the file is sparse and any
+ * key may be absent. The keys the shared options schema owns (`theme`,
+ * `width`, `pdfPageSize`, `assetRoot`) take their types from
+ * `SurfaceRcValues`; nothing here is validated until a surface resolves it.
  */
-export interface NowlineRc {
-    quiet?: boolean;
+export interface NowlineRc extends SurfaceRcValues {
     format?: string;
-    theme?: string;
     defaultFormat?: string;
-    width?: number;
-    pdfPageSize?: string;
     pdfOrientation?: string;
     pdfMargin?: string;
     fontSans?: string;
@@ -38,10 +37,4 @@ export interface LoadConfigOptions {
  */
 export declare function loadConfig(startDir: string, options?: LoadConfigOptions): Promise<LoadConfigResult>;
 export declare function parseConfig(contents: string, source: string): NowlineRc;
-/**
- * Layer flag values on top of a parsed config. `undefined` flag values
- * leave the underlying config key untouched — useful for "missing CLI
- * flag" semantics. Returned object is a shallow merge.
- */
-export declare function mergeConfig<T extends NowlineRc>(config: NowlineRc, flags: Partial<T>): T;
 //# sourceMappingURL=load-config.d.ts.map

package/dist/load-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-config.d.ts","sourceRoot":"","sources":["../src/load-config.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,sFAAsF;IACtF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,SAAS,CAAC;IAClB,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;GAIG;AACH,wBAAsB,UAAU,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,iBAAsB,GAChC,OAAO,CAAC,gBAAgB,CAAC,CAsB3B;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAUvE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAOxF"}
+{"version":3,"file":"load-config.d.ts","sourceRoot":"","sources":["../src/load-config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,SAAU,SAAQ,eAAe;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,sFAAsF;IACtF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,SAAS,CAAC;IAClB,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;GAIG;AACH,wBAAsB,UAAU,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,iBAAsB,GAChC,OAAO,CAAC,gBAAgB,CAAC,CAsB3B;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAUvE"}

package/dist/load-config.js

@@ -39,20 +39,6 @@ export function parseConfig(contents, source) {
     }
     return parsed;
 }
-/**
- * Layer flag values on top of a parsed config. `undefined` flag values
- * leave the underlying config key untouched — useful for "missing CLI
- * flag" semantics. Returned object is a shallow merge.
- */
-export function mergeConfig(config, flags) {
-    const merged = { ...config };
-    for (const [key, value] of Object.entries(flags)) {
-        if (value === undefined)
-            continue;
-        merged[key] = value;
-    }
-    return merged;
-}
 function parseJsonOrYaml(contents, source) {
     if (contents.startsWith('{') || contents.startsWith('[')) {
         try {

package/dist/load-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"load-config.js","sourceRoot":"","sources":["../src/load-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"load-config.js","sourceRoot":"","sources":["../src/load-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,SAAS,CAAC;AAqChC,MAAM,eAAe,GAAG,YAAY,CAAC;AAErC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC5B,QAAgB,EAChB,OAAO,GAAsB,EAAE;IAE/B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IACtE,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,iBAAiB,CAAC;IAC3D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,eAAe,CAAC;IACrD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;IAEnF,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC,OAAO,IAAI,EAAE,CAAC;QACV,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC3C,IAAI,MAAM,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,CAAC;YAC3C,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACzE,CAAC;QACD,IAAI,GAAG,KAAK,OAAO;YAAE,MAAM;QAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACjB,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,MAAc;IACxD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAChC,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IAC9B,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAChD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACzE,MAAM,IAAI,KAAK,CACX,WAAW,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,kCAAkC,MAAM,GAAG,CAC9E,CAAC;IACN,CAAC;IACD,OAAO,MAAmB,CAAC;AAC/B,CAAC;AAED,SAAS,eAAe,CAAC,QAAgB,EAAE,MAAc;IACrD,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACvD,IAAI,CAAC;YACD,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,KAAK,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrE,CAAC;IACL,CAAC;IACD,IAAI,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,KAAK,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;AACL,CAAC;AAED,SAAS,UAAU,CAAC,GAAY;IAC5B,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC5D,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,OAAe;IAC5C,IAAI,CAAC;QACD,MAAM,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,KAAK,CAAC;IACjB,CAAC;AACL,CAAC"}

package/dist/surface-options.d.ts

@@ -0,0 +1,160 @@
+import { type PdfPageSize } from '@nowline/export-core';
+import { type NonWorkingDisplay, type NormalizedZone, type ThemeName } from '@nowline/layout';
+export type SurfaceOptionKey = 'theme' | 'width' | 'now' | 'pageSize' | 'nonWorking';
+export interface SurfaceOptions {
+    theme: ThemeName;
+    /** Integer ≥ 320; undefined fits the content. */
+    width?: number;
+    /** The now-line date (UTC midnight); undefined suppresses it. */
+    today?: Date;
+    pageSize?: PdfPageSize;
+    /** Undefined lets the file's `default roadmap non-working:` key apply. */
+    nonWorking?: NonWorkingDisplay;
+}
+/** Where a raw value came from: what an error must name. */
+export type OptionSource = {
+    kind: 'flag';
+    name: string;
+} | {
+    kind: 'rc';
+    key: string;
+} | {
+    kind: 'argument';
+    name: string;
+} | {
+    kind: 'setting';
+    name: string;
+};
+/**
+ * One source's raw values. Layers are passed highest precedence first. `K`
+ * widens past the shared keys when a surface registers its own specs, and a
+ * layer over the union serves both resolutions.
+ */
+export interface OptionLayer<K extends string = SurfaceOptionKey> {
+    source: (key: K) => OptionSource;
+    values: Partial<Record<K, unknown>>;
+}
+export interface OptionError<K extends string = SurfaceOptionKey> {
+    key: K;
+    source: OptionSource;
+    raw: unknown;
+    /** What was wrong, without a lead: `must be an integer ≥ 320`. */
+    detail: string;
+    /** The accepted values, for an enum option. */
+    expected?: readonly string[];
+}
+export interface NowPolicy {
+    /** Zone for "today" when no layer sets `now`; local when omitted. */
+    zone?: NormalizedZone;
+    clock?: () => Date;
+}
+/**
+ * A parser's verdict on the winning raw value. `value: undefined` is an
+ * explicit "unset" (an empty `--width ""`): the option stays at its default
+ * and lower layers are not consulted.
+ */
+export type OptionParse<T> = {
+    ok: true;
+    value: T | undefined;
+} | {
+    ok: false;
+    detail: string;
+    expected?: readonly string[];
+};
+/** How one option is read: its `.nowlinerc` key, when it has one, and its parser. */
+export interface OptionSpec<T> {
+    rcKey?: string;
+    parse: (raw: unknown) => OptionParse<T>;
+}
+/**
+ * A set of option specs keyed by option name. The shared table is
+ * {@link SURFACE_OPTION_SPECS}; a surface registers its own keys (the CLI's
+ * `defaultFormat`, `pdfMargin`, ...) by passing its own table to
+ * {@link resolveOptions} and {@link rcLayer} over the same layers.
+ */
+export type OptionSpecTable<S> = {
+    readonly [K in keyof S]: OptionSpec<unknown>;
+};
+/** The parsed values of a spec table; a key is absent when no layer set it. */
+export type OptionValues<S extends OptionSpecTable<S>> = {
+    [K in keyof S]?: S[K] extends OptionSpec<infer V> ? V : never;
+};
+/** The string keys of a spec table. */
+export type OptionKeyOf<S> = Extract<keyof S, string>;
+/**
+ * The `.nowlinerc` key of every setting the schema owns; `undefined` means
+ * the option has no rc key. `assetRoot` is the default for `--asset-root`
+ * (specs/surface-options.md §7, decision 5). It is not a shared option (a
+ * path means something different to each surface), so it has its own spec,
+ * {@link ASSET_ROOT_SPEC}, that a surface adds to its table.
+ */
+export declare const SURFACE_RC_KEYS: Readonly<{
+    readonly theme: 'theme';
+    readonly width: 'width';
+    readonly now: undefined;
+    readonly pageSize: 'pdfPageSize';
+    readonly nonWorking: undefined;
+    readonly assetRoot: 'assetRoot';
+}>;
+/**
+ * The value types of the `.nowlinerc` keys the schema owns, as a file may
+ * hold them before parsing. `NowlineRc` extends this.
+ */
+export interface SurfaceRcValues {
+    /** A theme name, case-insensitive; `greyscale` is accepted. */
+    theme?: string;
+    /** Integer ≥ 320. A string is read with `parseInt`, as the CLI always has. */
+    width?: number | string;
+    /** A preset name, `content`, or `<W>x<H><unit>`. */
+    pdfPageSize?: string;
+    /** Base directory for `logo:` assets. */
+    assetRoot?: string;
+}
+/** The narrowest width a surface accepts, in px. */
+export declare const MIN_WIDTH = 320;
+/**
+ * How `assetRoot` is read: a path, kept as written. Resolving a relative one
+ * is the surface's job, because the base differs: a flag or setting resolves
+ * against the working directory, an rc value against the `.nowlinerc`'s own
+ * directory. Empty means unset.
+ */
+export declare const ASSET_ROOT_SPEC: Readonly<OptionSpec<string>>;
+export interface SurfaceOptionSpecs {
+    theme: OptionSpec<ThemeName>;
+    width: OptionSpec<number>;
+    /** `null` is the parsed `-` (suppress the now-line). */
+    now: OptionSpec<Date | null>;
+    pageSize: OptionSpec<PdfPageSize>;
+    nonWorking: OptionSpec<NonWorkingDisplay>;
+}
+/** The shared option specs, in the order their errors are reported. */
+export declare const SURFACE_OPTION_SPECS: Readonly<SurfaceOptionSpecs>;
+/**
+ * Resolve every option in `specs` over `layers` (highest precedence first).
+ * For each option the first layer holding a value other than `undefined` or
+ * `null` wins and is parsed; lower layers are never read for it, so a bad
+ * value below a valid one is not reported. A bad winning value is reported
+ * and the option is left unset. Errors follow the table's key order.
+ */
+export declare function resolveOptions<S extends OptionSpecTable<S>>(specs: S, layers: readonly OptionLayer<OptionKeyOf<S>>[]): {
+    values: OptionValues<S>;
+    errors: OptionError<OptionKeyOf<S>>[];
+};
+/**
+ * Resolve the shared options. With no `now` from any layer (or a bad one),
+ * the now-line is today's civil date in `now.zone`; a `-` suppresses it.
+ */
+export declare function resolveSurfaceOptions(layers: readonly OptionLayer[], defaults: {
+    theme: ThemeName;
+}, now: NowPolicy): {
+    options: SurfaceOptions;
+    errors: OptionError[];
+};
+/**
+ * Turn a loaded `.nowlinerc` into a layer: each spec with an `rcKey` reads
+ * that key, and an error names it. Pass a surface's own spec table to read
+ * its keys; with none, the shared specs are read.
+ */
+export declare function rcLayer(config: Readonly<Record<string, unknown>>): OptionLayer;
+export declare function rcLayer<S extends OptionSpecTable<S>>(config: Readonly<Record<string, unknown>>, specs: S): OptionLayer<OptionKeyOf<S>>;
+//# sourceMappingURL=surface-options.d.ts.map

package/dist/surface-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-options.d.ts","sourceRoot":"","sources":["../src/surface-options.ts"],"names":[],"mappings":"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"}

package/dist/surface-options.js

@@ -0,0 +1,182 @@
+// The options every render surface shares: theme, width, now, page size and
+// non-working display (specs/surface-options.md §3.1). Each option is parsed
+// once, here, from whatever layers a surface stacks (flags, MCP arguments,
+// editor settings, `.nowlinerc`), so a value accepted by one surface is
+// accepted by all of them. Errors come back as fields, not text: each surface
+// keeps its own message templates.
+import { PageSizeParseError, parsePageSize } from '@nowline/export-core';
+import { hasImpossibleNowDate, isNonWorkingDisplay, NON_WORKING_DISPLAYS, normalizeThemeName, resolveToday, THEME_NAMES, } from '@nowline/layout';
+// ---- `.nowlinerc` keys ------------------------------------------------------
+/**
+ * The `.nowlinerc` key of every setting the schema owns; `undefined` means
+ * the option has no rc key. `assetRoot` is the default for `--asset-root`
+ * (specs/surface-options.md §7, decision 5). It is not a shared option (a
+ * path means something different to each surface), so it has its own spec,
+ * {@link ASSET_ROOT_SPEC}, that a surface adds to its table.
+ */
+export const SURFACE_RC_KEYS = Object.freeze({
+    theme: 'theme',
+    width: 'width',
+    now: undefined,
+    pageSize: 'pdfPageSize',
+    nonWorking: undefined,
+    assetRoot: 'assetRoot',
+});
+// ---- Option specs -----------------------------------------------------------
+/** The narrowest width a surface accepts, in px. */
+export const MIN_WIDTH = 320;
+const NOW_DETAIL = 'must be YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS[Z|±HH:MM], or "-"';
+// `2026-02-30` has the right shape but names no day; it is an error, not March 2.
+const NOW_REAL_DAY_DETAIL = 'must be a real calendar date';
+function parseTheme(raw) {
+    const theme = typeof raw === 'string' ? normalizeThemeName(raw) : undefined;
+    if (theme)
+        return { ok: true, value: theme };
+    return { ok: false, detail: 'must be a theme name', expected: THEME_NAMES };
+}
+// The CLI's rule, kept exactly: a string goes through `parseInt`, so
+// `"1200px"` reads as 1200; anything else must already be a number.
+function parseWidth(raw) {
+    if (raw === '')
+        return { ok: true, value: undefined };
+    const value = typeof raw === 'number'
+        ? raw
+        : typeof raw === 'string'
+            ? Number.parseInt(raw, 10)
+            : Number.NaN;
+    if (Number.isInteger(value) && value >= MIN_WIDTH)
+        return { ok: true, value };
+    return { ok: false, detail: `must be an integer ≥ ${MIN_WIDTH}` };
+}
+// `null` is a parsed `-`: the now-line is suppressed.
+function parseNow(raw) {
+    if (raw instanceof Date) {
+        if (!Number.isNaN(raw.getTime()))
+            return { ok: true, value: raw };
+    }
+    else if (raw === '-') {
+        return { ok: true, value: null };
+    }
+    else if (typeof raw === 'string') {
+        const today = resolveToday({ now: raw });
+        if (today)
+            return { ok: true, value: today };
+        if (hasImpossibleNowDate(raw))
+            return { ok: false, detail: NOW_REAL_DAY_DETAIL };
+    }
+    return { ok: false, detail: NOW_DETAIL };
+}
+function parsePageSizeOption(raw) {
+    if (raw === '')
+        return { ok: true, value: undefined };
+    try {
+        return { ok: true, value: parsePageSize(String(raw)) };
+    }
+    catch (err) {
+        if (!(err instanceof PageSizeParseError))
+            throw err;
+        // The parser names a generic "page size"; the surface supplies the lead.
+        return { ok: false, detail: err.message.replace(/^invalid page size "[^"]*": /, '') };
+    }
+}
+function parseNonWorking(raw) {
+    if (raw === '')
+        return { ok: true, value: undefined };
+    if (isNonWorkingDisplay(raw))
+        return { ok: true, value: raw };
+    return { ok: false, detail: 'must be a non-working display', expected: NON_WORKING_DISPLAYS };
+}
+function parseAssetRoot(raw) {
+    if (raw === '')
+        return { ok: true, value: undefined };
+    if (typeof raw === 'string')
+        return { ok: true, value: raw };
+    return { ok: false, detail: 'must be a directory path' };
+}
+/**
+ * How `assetRoot` is read: a path, kept as written. Resolving a relative one
+ * is the surface's job, because the base differs: a flag or setting resolves
+ * against the working directory, an rc value against the `.nowlinerc`'s own
+ * directory. Empty means unset.
+ */
+export const ASSET_ROOT_SPEC = Object.freeze({
+    rcKey: SURFACE_RC_KEYS.assetRoot,
+    parse: parseAssetRoot,
+});
+/** The shared option specs, in the order their errors are reported. */
+export const SURFACE_OPTION_SPECS = Object.freeze({
+    theme: { rcKey: SURFACE_RC_KEYS.theme, parse: parseTheme },
+    width: { rcKey: SURFACE_RC_KEYS.width, parse: parseWidth },
+    now: { parse: parseNow },
+    pageSize: { rcKey: SURFACE_RC_KEYS.pageSize, parse: parsePageSizeOption },
+    nonWorking: { parse: parseNonWorking },
+});
+// ---- Resolution -------------------------------------------------------------
+/**
+ * Resolve every option in `specs` over `layers` (highest precedence first).
+ * For each option the first layer holding a value other than `undefined` or
+ * `null` wins and is parsed; lower layers are never read for it, so a bad
+ * value below a valid one is not reported. A bad winning value is reported
+ * and the option is left unset. Errors follow the table's key order.
+ */
+export function resolveOptions(specs, layers) {
+    const values = {};
+    const errors = [];
+    for (const key of Object.keys(specs)) {
+        const layer = layers.find((candidate) => isGiven(candidate.values[key]));
+        if (!layer)
+            continue;
+        const raw = layer.values[key];
+        const parsed = specs[key].parse(raw);
+        if (!parsed.ok) {
+            const error = {
+                key,
+                source: layer.source(key),
+                raw,
+                detail: parsed.detail,
+            };
+            if (parsed.expected)
+                error.expected = parsed.expected;
+            errors.push(error);
+        }
+        else if (parsed.value !== undefined) {
+            values[key] = parsed.value;
+        }
+    }
+    return { values, errors };
+}
+/**
+ * Resolve the shared options. With no `now` from any layer (or a bad one),
+ * the now-line is today's civil date in `now.zone`; a `-` suppresses it.
+ */
+export function resolveSurfaceOptions(layers, defaults, now) {
+    const { values, errors } = resolveOptions(SURFACE_OPTION_SPECS, layers);
+    const today = values.now === undefined
+        ? resolveToday({ zone: now.zone, clock: now.clock })
+        : (values.now ?? undefined);
+    const options = { theme: values.theme ?? defaults.theme };
+    if (values.width !== undefined)
+        options.width = values.width;
+    if (today !== undefined)
+        options.today = today;
+    if (values.pageSize !== undefined)
+        options.pageSize = values.pageSize;
+    if (values.nonWorking !== undefined)
+        options.nonWorking = values.nonWorking;
+    return { options, errors };
+}
+export function rcLayer(config, specs = SURFACE_OPTION_SPECS) {
+    const values = {};
+    for (const [key, spec] of Object.entries(specs)) {
+        if (spec.rcKey !== undefined)
+            values[key] = config[spec.rcKey];
+    }
+    return {
+        source: (key) => ({ kind: 'rc', key: specs[key]?.rcKey ?? key }),
+        values,
+    };
+}
+function isGiven(value) {
+    return value !== undefined && value !== null;
+}
+//# sourceMappingURL=surface-options.js.map

package/dist/surface-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-options.js","sourceRoot":"","sources":["../src/surface-options.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,6EAA6E;AAC7E,2EAA2E;AAC3E,wEAAwE;AACxE,8EAA8E;AAC9E,mCAAmC;AAEnC,OAAO,EAAE,kBAAkB,EAAoB,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACH,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EAGpB,kBAAkB,EAClB,YAAY,EACZ,WAAW,GAEd,MAAM,iBAAiB,CAAC;AAiFzB,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IACzC,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,GAAG,EAAE,SAAS;IACd,QAAQ,EAAE,aAAa;IACvB,UAAU,EAAE,SAAS;IACrB,SAAS,EAAE,WAAW;CACqD,CAAC,CAAC;AAiBjF,gFAAgF;AAEhF,oDAAoD;AACpD,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,CAAC;AAE7B,MAAM,UAAU,GAAG,2DAA2D,CAAC;AAC/E,kFAAkF;AAClF,MAAM,mBAAmB,GAAG,8BAA8B,CAAC;AAE3D,SAAS,UAAU,CAAC,GAAY;IAC5B,MAAM,KAAK,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5E,IAAI,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC7C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AAChF,CAAC;AAED,qEAAqE;AACrE,oEAAoE;AACpE,SAAS,UAAU,CAAC,GAAY;IAC5B,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACtD,MAAM,KAAK,GACP,OAAO,GAAG,KAAK,QAAQ;QACnB,CAAC,CAAC,GAAG;QACL,CAAC,CAAC,OAAO,GAAG,KAAK,QAAQ;YACvB,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC;YAC1B,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;IACvB,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC9E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wBAAwB,SAAS,EAAE,EAAE,CAAC;AACtE,CAAC;AAED,sDAAsD;AACtD,SAAS,QAAQ,CAAC,GAAY;IAC1B,IAAI,GAAG,YAAY,IAAI,EAAE,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACtE,CAAC;SAAM,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;QACrB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACrC,CAAC;SAAM,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;QACzC,IAAI,KAAK;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAC7C,IAAI,oBAAoB,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACrF,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AAC7C,CAAC;AAED,SAAS,mBAAmB,CAAC,GAAY;IACrC,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACtD,IAAI,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;IAC3D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACX,IAAI,CAAC,CAAC,GAAG,YAAY,kBAAkB,CAAC;YAAE,MAAM,GAAG,CAAC;QACpD,yEAAyE;QACzE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,8BAA8B,EAAE,EAAE,CAAC,EAAE,CAAC;IAC1F,CAAC;AACL,CAAC;AAED,SAAS,eAAe,CAAC,GAAY;IACjC,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACtD,IAAI,mBAAmB,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAC9D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,+BAA+B,EAAE,QAAQ,EAAE,oBAAoB,EAAE,CAAC;AAClG,CAAC;AAED,SAAS,cAAc,CAAC,GAAY;IAChC,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACtD,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAC7D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;AAC7D,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAiC,MAAM,CAAC,MAAM,CAAC;IACvE,KAAK,EAAE,eAAe,CAAC,SAAS;IAChC,KAAK,EAAE,cAAc;CACxB,CAAC,CAAC;AAWH,uEAAuE;AACvE,MAAM,CAAC,MAAM,oBAAoB,GAAiC,MAAM,CAAC,MAAM,CAAC;IAC5E,KAAK,EAAE,EAAE,KAAK,EAAE,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE;IAC1D,KAAK,EAAE,EAAE,KAAK,EAAE,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE;IAC1D,GAAG,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE;IACxB,QAAQ,EAAE,EAAE,KAAK,EAAE,eAAe,CAAC,QAAQ,EAAE,KAAK,EAAE,mBAAmB,EAAE;IACzE,UAAU,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE;CACzC,CAAC,CAAC;AAEH,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC1B,KAAQ,EACR,MAA8C;IAE9C,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,MAAM,MAAM,GAAkC,EAAE,CAAC;IACjD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAqB,EAAE,CAAC;QACvD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACzE,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,KAAK,GAAgC;gBACvC,GAAG;gBACH,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC;gBACzB,GAAG;gBACH,MAAM,EAAE,MAAM,CAAC,MAAM;aACxB,CAAC;YACF,IAAI,MAAM,CAAC,QAAQ;gBAAE,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;YACtD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;aAAM,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YACpC,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,KAAwC,CAAC;QAClE,CAAC;IACL,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACjC,MAA8B,EAC9B,QAA8B,EAC9B,GAAc;IAEd,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;IACxE,MAAM,KAAK,GACP,MAAM,CAAC,GAAG,KAAK,SAAS;QACpB,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;QACpD,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,SAAS,CAAC,CAAC;IACpC,MAAM,OAAO,GAAmB,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;IAC1E,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC7D,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;IAC/C,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IACtE,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IAC5E,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC/B,CAAC;AAYD,MAAM,UAAU,OAAO,CACnB,MAAyC,EACzC,KAAK,GAAkD,oBAAoB;IAE3E,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9C,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnE,CAAC;IACD,OAAO;QACH,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,KAAK,IAAI,GAAG,EAAE,CAAC;QAChE,MAAM;KACT,CAAC;AACN,CAAC;AAED,SAAS,OAAO,CAAC,KAAc;IAC3B,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC;AACjD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nowline/config",
-  "version": "0.8.6",
+  "version": "0.9.0",
   "description": "Loads Nowline project settings (the .nowlinerc file) for the CLI and editor integrations.",
   "license": "Apache-2.0",
   "engines": {
@@ -21,12 +21,14 @@
     "src/"
   ],
   "dependencies": {
-    "js-yaml": "^5.4.2"
+    "@nowline/export-core": "0.9.0",
+    "@nowline/layout": "0.9.0",
+    "js-yaml": "^5.5.0"
   },
   "devDependencies": {
-    "@types/node": "^26.6.3",
+    "@types/node": "^26.6.5",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.5"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json",

package/src/index.ts

@@ -2,7 +2,28 @@ export {
     type LoadConfigOptions,
     type LoadConfigResult,
     loadConfig,
-    mergeConfig,
     type NowlineRc,
     parseConfig,
 } from './load-config.js';
+export {
+    ASSET_ROOT_SPEC,
+    MIN_WIDTH,
+    type NowPolicy,
+    type OptionError,
+    type OptionKeyOf,
+    type OptionLayer,
+    type OptionParse,
+    type OptionSource,
+    type OptionSpec,
+    type OptionSpecTable,
+    type OptionValues,
+    rcLayer,
+    resolveOptions,
+    resolveSurfaceOptions,
+    SURFACE_OPTION_SPECS,
+    SURFACE_RC_KEYS,
+    type SurfaceOptionKey,
+    type SurfaceOptionSpecs,
+    type SurfaceOptions,
+    type SurfaceRcValues,
+} from './surface-options.js';

package/src/load-config.ts

@@ -1,19 +1,18 @@
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'js-yaml';
+import type { SurfaceRcValues } from './surface-options.js';
 
 /**
- * Shape of the `.nowlinerc` file consumed by the CLI today and (post-m3d)
- * by the VS Code/Cursor extension. Keys are intentionally optional — the
- * file is sparse and any key may be absent.
+ * Shape of the `.nowlinerc` file consumed by the CLI and the VS Code/Cursor
+ * extension. Keys are intentionally optional — the file is sparse and any
+ * key may be absent. The keys the shared options schema owns (`theme`,
+ * `width`, `pdfPageSize`, `assetRoot`) take their types from
+ * `SurfaceRcValues`; nothing here is validated until a surface resolves it.
  */
-export interface NowlineRc {
-    quiet?: boolean;
+export interface NowlineRc extends SurfaceRcValues {
     format?: string;
-    theme?: string;
     defaultFormat?: string;
-    width?: number;
-    pdfPageSize?: string;
     pdfOrientation?: string;
     pdfMargin?: string;
     fontSans?: string;
@@ -84,20 +83,6 @@ export function parseConfig(contents: string, source: string): NowlineRc {
     return parsed as NowlineRc;
 }
 
-/**
- * Layer flag values on top of a parsed config. `undefined` flag values
- * leave the underlying config key untouched — useful for "missing CLI
- * flag" semantics. Returned object is a shallow merge.
- */
-export function mergeConfig<T extends NowlineRc>(config: NowlineRc, flags: Partial<T>): T {
-    const merged: NowlineRc = { ...config };
-    for (const [key, value] of Object.entries(flags)) {
-        if (value === undefined) continue;
-        merged[key] = value as unknown;
-    }
-    return merged as T;
-}
-
 function parseJsonOrYaml(contents: string, source: string): unknown {
     if (contents.startsWith('{') || contents.startsWith('[')) {
         try {

package/src/surface-options.ts

@@ -0,0 +1,312 @@
+// The options every render surface shares: theme, width, now, page size and
+// non-working display (specs/surface-options.md §3.1). Each option is parsed
+// once, here, from whatever layers a surface stacks (flags, MCP arguments,
+// editor settings, `.nowlinerc`), so a value accepted by one surface is
+// accepted by all of them. Errors come back as fields, not text: each surface
+// keeps its own message templates.
+
+import { PageSizeParseError, type PdfPageSize, parsePageSize } from '@nowline/export-core';
+import {
+    hasImpossibleNowDate,
+    isNonWorkingDisplay,
+    NON_WORKING_DISPLAYS,
+    type NonWorkingDisplay,
+    type NormalizedZone,
+    normalizeThemeName,
+    resolveToday,
+    THEME_NAMES,
+    type ThemeName,
+} from '@nowline/layout';
+
+// ---- Public types -----------------------------------------------------------
+
+export type SurfaceOptionKey = 'theme' | 'width' | 'now' | 'pageSize' | 'nonWorking';
+
+export interface SurfaceOptions {
+    theme: ThemeName;
+    /** Integer ≥ 320; undefined fits the content. */
+    width?: number;
+    /** The now-line date (UTC midnight); undefined suppresses it. */
+    today?: Date;
+    pageSize?: PdfPageSize;
+    /** Undefined lets the file's `default roadmap non-working:` key apply. */
+    nonWorking?: NonWorkingDisplay;
+}
+
+/** Where a raw value came from: what an error must name. */
+export type OptionSource =
+    | { kind: 'flag'; name: string } // --width
+    | { kind: 'rc'; key: string } // .nowlinerc width
+    | { kind: 'argument'; name: string } // MCP width
+    | { kind: 'setting'; name: string }; // nowline.preview.width
+
+/**
+ * One source's raw values. Layers are passed highest precedence first. `K`
+ * widens past the shared keys when a surface registers its own specs, and a
+ * layer over the union serves both resolutions.
+ */
+export interface OptionLayer<K extends string = SurfaceOptionKey> {
+    source: (key: K) => OptionSource;
+    values: Partial<Record<K, unknown>>;
+}
+
+export interface OptionError<K extends string = SurfaceOptionKey> {
+    key: K;
+    source: OptionSource;
+    raw: unknown;
+    /** What was wrong, without a lead: `must be an integer ≥ 320`. */
+    detail: string;
+    /** The accepted values, for an enum option. */
+    expected?: readonly string[];
+}
+
+export interface NowPolicy {
+    /** Zone for "today" when no layer sets `now`; local when omitted. */
+    zone?: NormalizedZone;
+    clock?: () => Date;
+}
+
+/**
+ * A parser's verdict on the winning raw value. `value: undefined` is an
+ * explicit "unset" (an empty `--width ""`): the option stays at its default
+ * and lower layers are not consulted.
+ */
+export type OptionParse<T> =
+    | { ok: true; value: T | undefined }
+    | { ok: false; detail: string; expected?: readonly string[] };
+
+/** How one option is read: its `.nowlinerc` key, when it has one, and its parser. */
+export interface OptionSpec<T> {
+    rcKey?: string;
+    parse: (raw: unknown) => OptionParse<T>;
+}
+
+/**
+ * A set of option specs keyed by option name. The shared table is
+ * {@link SURFACE_OPTION_SPECS}; a surface registers its own keys (the CLI's
+ * `defaultFormat`, `pdfMargin`, ...) by passing its own table to
+ * {@link resolveOptions} and {@link rcLayer} over the same layers.
+ */
+export type OptionSpecTable<S> = { readonly [K in keyof S]: OptionSpec<unknown> };
+
+/** The parsed values of a spec table; a key is absent when no layer set it. */
+export type OptionValues<S extends OptionSpecTable<S>> = {
+    [K in keyof S]?: S[K] extends OptionSpec<infer V> ? V : never;
+};
+
+/** The string keys of a spec table. */
+export type OptionKeyOf<S> = Extract<keyof S, string>;
+
+// ---- `.nowlinerc` keys ------------------------------------------------------
+
+/**
+ * The `.nowlinerc` key of every setting the schema owns; `undefined` means
+ * the option has no rc key. `assetRoot` is the default for `--asset-root`
+ * (specs/surface-options.md §7, decision 5). It is not a shared option (a
+ * path means something different to each surface), so it has its own spec,
+ * {@link ASSET_ROOT_SPEC}, that a surface adds to its table.
+ */
+export const SURFACE_RC_KEYS = Object.freeze({
+    theme: 'theme',
+    width: 'width',
+    now: undefined,
+    pageSize: 'pdfPageSize',
+    nonWorking: undefined,
+    assetRoot: 'assetRoot',
+} as const satisfies Record<SurfaceOptionKey | 'assetRoot', string | undefined>);
+
+/**
+ * The value types of the `.nowlinerc` keys the schema owns, as a file may
+ * hold them before parsing. `NowlineRc` extends this.
+ */
+export interface SurfaceRcValues {
+    /** A theme name, case-insensitive; `greyscale` is accepted. */
+    theme?: string;
+    /** Integer ≥ 320. A string is read with `parseInt`, as the CLI always has. */
+    width?: number | string;
+    /** A preset name, `content`, or `<W>x<H><unit>`. */
+    pdfPageSize?: string;
+    /** Base directory for `logo:` assets. */
+    assetRoot?: string;
+}
+
+// ---- Option specs -----------------------------------------------------------
+
+/** The narrowest width a surface accepts, in px. */
+export const MIN_WIDTH = 320;
+
+const NOW_DETAIL = 'must be YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS[Z|±HH:MM], or "-"';
+// `2026-02-30` has the right shape but names no day; it is an error, not March 2.
+const NOW_REAL_DAY_DETAIL = 'must be a real calendar date';
+
+function parseTheme(raw: unknown): OptionParse<ThemeName> {
+    const theme = typeof raw === 'string' ? normalizeThemeName(raw) : undefined;
+    if (theme) return { ok: true, value: theme };
+    return { ok: false, detail: 'must be a theme name', expected: THEME_NAMES };
+}
+
+// The CLI's rule, kept exactly: a string goes through `parseInt`, so
+// `"1200px"` reads as 1200; anything else must already be a number.
+function parseWidth(raw: unknown): OptionParse<number> {
+    if (raw === '') return { ok: true, value: undefined };
+    const value =
+        typeof raw === 'number'
+            ? raw
+            : typeof raw === 'string'
+              ? Number.parseInt(raw, 10)
+              : Number.NaN;
+    if (Number.isInteger(value) && value >= MIN_WIDTH) return { ok: true, value };
+    return { ok: false, detail: `must be an integer ≥ ${MIN_WIDTH}` };
+}
+
+// `null` is a parsed `-`: the now-line is suppressed.
+function parseNow(raw: unknown): OptionParse<Date | null> {
+    if (raw instanceof Date) {
+        if (!Number.isNaN(raw.getTime())) return { ok: true, value: raw };
+    } else if (raw === '-') {
+        return { ok: true, value: null };
+    } else if (typeof raw === 'string') {
+        const today = resolveToday({ now: raw });
+        if (today) return { ok: true, value: today };
+        if (hasImpossibleNowDate(raw)) return { ok: false, detail: NOW_REAL_DAY_DETAIL };
+    }
+    return { ok: false, detail: NOW_DETAIL };
+}
+
+function parsePageSizeOption(raw: unknown): OptionParse<PdfPageSize> {
+    if (raw === '') return { ok: true, value: undefined };
+    try {
+        return { ok: true, value: parsePageSize(String(raw)) };
+    } catch (err) {
+        if (!(err instanceof PageSizeParseError)) throw err;
+        // The parser names a generic "page size"; the surface supplies the lead.
+        return { ok: false, detail: err.message.replace(/^invalid page size "[^"]*": /, '') };
+    }
+}
+
+function parseNonWorking(raw: unknown): OptionParse<NonWorkingDisplay> {
+    if (raw === '') return { ok: true, value: undefined };
+    if (isNonWorkingDisplay(raw)) return { ok: true, value: raw };
+    return { ok: false, detail: 'must be a non-working display', expected: NON_WORKING_DISPLAYS };
+}
+
+function parseAssetRoot(raw: unknown): OptionParse<string> {
+    if (raw === '') return { ok: true, value: undefined };
+    if (typeof raw === 'string') return { ok: true, value: raw };
+    return { ok: false, detail: 'must be a directory path' };
+}
+
+/**
+ * How `assetRoot` is read: a path, kept as written. Resolving a relative one
+ * is the surface's job, because the base differs: a flag or setting resolves
+ * against the working directory, an rc value against the `.nowlinerc`'s own
+ * directory. Empty means unset.
+ */
+export const ASSET_ROOT_SPEC: Readonly<OptionSpec<string>> = Object.freeze({
+    rcKey: SURFACE_RC_KEYS.assetRoot,
+    parse: parseAssetRoot,
+});
+
+export interface SurfaceOptionSpecs {
+    theme: OptionSpec<ThemeName>;
+    width: OptionSpec<number>;
+    /** `null` is the parsed `-` (suppress the now-line). */
+    now: OptionSpec<Date | null>;
+    pageSize: OptionSpec<PdfPageSize>;
+    nonWorking: OptionSpec<NonWorkingDisplay>;
+}
+
+/** The shared option specs, in the order their errors are reported. */
+export const SURFACE_OPTION_SPECS: Readonly<SurfaceOptionSpecs> = Object.freeze({
+    theme: { rcKey: SURFACE_RC_KEYS.theme, parse: parseTheme },
+    width: { rcKey: SURFACE_RC_KEYS.width, parse: parseWidth },
+    now: { parse: parseNow },
+    pageSize: { rcKey: SURFACE_RC_KEYS.pageSize, parse: parsePageSizeOption },
+    nonWorking: { parse: parseNonWorking },
+});
+
+// ---- Resolution -------------------------------------------------------------
+
+/**
+ * Resolve every option in `specs` over `layers` (highest precedence first).
+ * For each option the first layer holding a value other than `undefined` or
+ * `null` wins and is parsed; lower layers are never read for it, so a bad
+ * value below a valid one is not reported. A bad winning value is reported
+ * and the option is left unset. Errors follow the table's key order.
+ */
+export function resolveOptions<S extends OptionSpecTable<S>>(
+    specs: S,
+    layers: readonly OptionLayer<OptionKeyOf<S>>[],
+): { values: OptionValues<S>; errors: OptionError<OptionKeyOf<S>>[] } {
+    const values: OptionValues<S> = {};
+    const errors: OptionError<OptionKeyOf<S>>[] = [];
+    for (const key of Object.keys(specs) as OptionKeyOf<S>[]) {
+        const layer = layers.find((candidate) => isGiven(candidate.values[key]));
+        if (!layer) continue;
+        const raw = layer.values[key];
+        const parsed = specs[key].parse(raw);
+        if (!parsed.ok) {
+            const error: OptionError<OptionKeyOf<S>> = {
+                key,
+                source: layer.source(key),
+                raw,
+                detail: parsed.detail,
+            };
+            if (parsed.expected) error.expected = parsed.expected;
+            errors.push(error);
+        } else if (parsed.value !== undefined) {
+            values[key] = parsed.value as OptionValues<S>[OptionKeyOf<S>];
+        }
+    }
+    return { values, errors };
+}
+
+/**
+ * Resolve the shared options. With no `now` from any layer (or a bad one),
+ * the now-line is today's civil date in `now.zone`; a `-` suppresses it.
+ */
+export function resolveSurfaceOptions(
+    layers: readonly OptionLayer[],
+    defaults: { theme: ThemeName },
+    now: NowPolicy,
+): { options: SurfaceOptions; errors: OptionError[] } {
+    const { values, errors } = resolveOptions(SURFACE_OPTION_SPECS, layers);
+    const today =
+        values.now === undefined
+            ? resolveToday({ zone: now.zone, clock: now.clock })
+            : (values.now ?? undefined);
+    const options: SurfaceOptions = { theme: values.theme ?? defaults.theme };
+    if (values.width !== undefined) options.width = values.width;
+    if (today !== undefined) options.today = today;
+    if (values.pageSize !== undefined) options.pageSize = values.pageSize;
+    if (values.nonWorking !== undefined) options.nonWorking = values.nonWorking;
+    return { options, errors };
+}
+
+/**
+ * Turn a loaded `.nowlinerc` into a layer: each spec with an `rcKey` reads
+ * that key, and an error names it. Pass a surface's own spec table to read
+ * its keys; with none, the shared specs are read.
+ */
+export function rcLayer(config: Readonly<Record<string, unknown>>): OptionLayer;
+export function rcLayer<S extends OptionSpecTable<S>>(
+    config: Readonly<Record<string, unknown>>,
+    specs: S,
+): OptionLayer<OptionKeyOf<S>>;
+export function rcLayer(
+    config: Readonly<Record<string, unknown>>,
+    specs: Readonly<Record<string, OptionSpec<unknown>>> = SURFACE_OPTION_SPECS,
+): OptionLayer<string> {
+    const values: Record<string, unknown> = {};
+    for (const [key, spec] of Object.entries(specs)) {
+        if (spec.rcKey !== undefined) values[key] = config[spec.rcKey];
+    }
+    return {
+        source: (key) => ({ kind: 'rc', key: specs[key]?.rcKey ?? key }),
+        values,
+    };
+}
+
+function isGiven(value: unknown): boolean {
+    return value !== undefined && value !== null;
+}