@overpunch/vf-clamp 2.1.4 → 2.3.0

package/dist/index.cjs

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const N=require("node:module");var g=typeof document<"u"?document.currentScript:null;const O=N.createRequire(typeof document>"u"?require("url").pathToFileURL(__filename).href:g&&g.tagName.toUpperCase()==="SCRIPT"&&g.src||new URL("index.cjs",document.baseURI).href),{preparePyodide:l,PyodideFile:u}=O("@web-alchemy/fonttools/src/pyodide.js");let h=null;async function j(){return h||(h=l().then(e=>e.runPythonAsync(`
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const U=require("node:module");var I=typeof document<"u"?document.currentScript:null;const E=U.createRequire(typeof document>"u"?require("url").pathToFileURL(__filename).href:I&&I.tagName.toUpperCase()==="SCRIPT"&&I.src||new URL("index.cjs",document.baseURI).href),{preparePyodide:d,PyodideFile:x}=E("@web-alchemy/fonttools/src/pyodide.js");let S=null;async function B(){return S||(S=d().then(e=>e.runPythonAsync(`
 from fontTools.ttLib import TTFont
 
 def vf_convert_flavor(file_options):
@@ -7,15 +7,16 @@ def vf_convert_flavor(file_options):
     font.save(file_options['output-file'])
 
 vf_convert_flavor
-`))),h}async function V(e,o){const a=await l(),t=new u({pyodide:a}),n=new u({pyodide:a});try{await t.upload(e);const i=new Map([["input-file",t.filename],["output-file",n.filename],["flavor",o]]);return(await j())(i),n.download()}finally{try{t.delete()}catch{}try{n.delete()}catch{}}}async function I(e){return V(e,"woff")}async function D(e){return V(e,"woff2")}let w=null;async function L(){return w||(w=l().then(e=>e.runPythonAsync(`
+`))),S}async function P(e,a){const t=await d(),n=new x({pyodide:t}),i=new x({pyodide:t});try{await n.upload(e);const o=new Map([["input-file",n.filename],["output-file",i.filename],["flavor",a]]);return(await B())(o),i.download()}finally{try{n.delete()}catch{}try{i.delete()}catch{}}}async function $(e){return P(e,"woff")}async function L(e){return P(e,"woff2")}let A=null;async function W(){return A||(A=d().then(e=>e.runPythonAsync(`
 import json
 from fontTools.ttLib import TTFont
 
 def get_instances_fn(input_file):
     font = TTFont(input_file)
 
+    family = font['name'].getDebugName(16) or font['name'].getDebugName(1) or ''
     if 'fvar' not in font:
-        return json.dumps({'axes': [], 'instances': []})
+        return json.dumps({'axes': [], 'instances': [], 'family': family})
 
     fvar = font['fvar']
     name_table = font['name']
@@ -39,10 +40,10 @@ def get_instances_fn(input_file):
         for i, inst in enumerate(fvar.instances)
     ]
 
-    return json.dumps({'axes': axes, 'instances': instances})
+    return json.dumps({'axes': axes, 'instances': instances, 'family': family})
 
 get_instances_fn
-`))),w}async function R(e){const o=await l(),a=e instanceof ArrayBuffer?new Uint8Array(e):e,t=new u({pyodide:o});try{await t.upload(a);const i=(await L())(t.filename);return JSON.parse(i)}finally{try{t.delete()}catch{}}}let v=null,y=null,A=null,T=null,b=null;async function M(){return v||(v=l().then(e=>e.runPythonAsync(`
+`))),A}async function M(e){const a=await d(),t=e instanceof ArrayBuffer?new Uint8Array(e):e,n=new x({pyodide:a});try{await n.upload(t);const o=(await W())(n.filename);return JSON.parse(o)}finally{try{n.delete()}catch{}}}function C(e,a){if(e===a)return e;const t=e.split(" "),n=a.split(" ");let i=0;for(;i<t.length&&i<n.length&&t[i]===n[i];)i++;let o=0;for(;o<t.length-i&&o<n.length-i&&t[t.length-1-o]===n[n.length-1-o];)o++;const r=t.slice(0,i).join(" "),s=t.slice(i,t.length-(o||0)).join(" "),h=n.slice(i,n.length-(o||0)).join(" "),y=o>0?t.slice(t.length-o).join(" "):"",f=s&&h?`${s}-${h}`:s||h;return[r,f,y].filter(Boolean).join(" ")}function T(e,a){const t=a.filter(n=>n.name===e);if(!t.length)throw new Error(`Named instance "${e}" not found in font`);if(t.length>1)throw new Error(`Named instance "${e}" is ambiguous: ${t.length} instances share that name`);return t[0]}let V=null,N=null,D=null,O=null;async function z(){return V||(V=d().then(e=>e.runPythonAsync(`
 from fontTools import ttLib
 
 def patch_font_names_fn(file_options):
@@ -53,6 +54,27 @@ def patch_font_names_fn(file_options):
 
     existing_ids = {r.nameID for r in name_table.names}
 
+    # A family name with no ASCII letters gives an empty PostScript name: fall back to the
+    # source PostScript name plus a short hash of the family name (passed in from JS).
+    if not ps_name:
+        source_ps = name_table.getDebugName(6) or 'Font'
+        ps_name = ('%s-%s' % (source_ps[:52], file_options['postscript-suffix']))[:63]
+
+    # nameID 2 must be a RIBBI style that matches OS/2 (already updated): Regular, Italic, Bold or Bold Italic.
+    fs = font['OS/2'].fsSelection if 'OS/2' in font else 0x40
+    is_italic = bool(fs & 0x01)
+    is_bold = bool(fs & 0x20)
+    ribbi = ('Bold Italic' if is_italic else 'Bold') if is_bold else ('Italic' if is_italic else 'Regular')
+
+    # nameID 17 (typographic subfamily): the name of the named instance at the new default, if any.
+    default_style = None
+    if 'fvar' in font:
+        defaults = {ax.axisTag: ax.defaultValue for ax in font['fvar'].axes}
+        for inst in font['fvar'].instances:
+            if all(abs(inst.coordinates.get(t, v) - v) < 0.01 for t, v in defaults.items()):
+                default_style = name_table.getDebugName(inst.subfamilyNameID)
+                break
+
     # nameID 1 = Family, 4 = Full name, 6 = PostScript name
     # nameID 2 = Subfamily — reset to 'Regular' so the restricted file does not
     #            collide with the source font's Subfamily in OS font caches.
@@ -70,32 +92,50 @@ def patch_font_names_fn(file_options):
 
     updates = {
         1: family_name,
-        2: 'Regular',
+        2: ribbi,
         3: unique_id,
-        4: family_name,
+        4: family_name if ribbi == 'Regular' else '%s %s' % (family_name, ribbi),
         6: ps_name,
     }
     if 16 in existing_ids:
         updates[16] = family_name
+    if 17 in existing_ids and default_style:
+        updates[17] = default_style
     if 25 in existing_ids:
         updates[25] = ps_name
 
+    # Named instances' PostScript names must follow the new prefix, e.g. Inter-Regular-Bold-Medium.
+    if 'fvar' in font:
+        for inst in font['fvar'].instances:
+            pid = getattr(inst, 'postscriptNameID', 0xFFFF)
+            if pid in (None, 0xFFFF):
+                continue
+            style = (name_table.getDebugName(inst.subfamilyNameID) or '').replace(' ', '')
+            style = ''.join(c for c in style if c.isascii() and (c.isalnum() or c == '-'))
+            updates[pid] = ('%s-%s' % (ps_name, style))[:63]
+
+    # Rewrite every platform. A Mac (platform 1) record that can't be encoded in Mac Roman is dropped
+    # rather than filled with '?'; Windows and Unicode records always carry the full name.
+    keep = []
     for record in name_table.names:
         if record.nameID not in updates:
+            keep.append(record)
             continue
         value = updates[record.nameID]
-        if record.platformID == 3:
+        if record.platformID in (0, 3):
             record.string = value.encode('utf-16-be')
         elif record.platformID == 1:
             try:
                 record.string = value.encode('mac_roman')
             except Exception:
-                record.string = value.encode('ascii', errors='replace')
+                continue
+        keep.append(record)
+    name_table.names = keep
 
     font.save(file_options['output-file'])
 
 patch_font_names_fn
-`))),v}async function U(){return y||(y=l().then(e=>e.runPythonAsync(`
+`))),V}async function q(){return N||(N=d().then(e=>e.runPythonAsync(`
 from fontTools.ttLib import TTFont
 from fontTools.varLib import instancer
 import json
@@ -104,6 +144,12 @@ def vf_clamp_instantiate(file_options, axes_json):
     font = TTFont(file_options['input-file'])
     axes_spec = json.loads(axes_json)
 
+    # The bundled fontTools can't restrict avar version 2 or VARC fonts correctly: refuse instead of mis-cutting.
+    if 'avar' in font and getattr(font['avar'], 'majorVersion', 1) >= 2:
+        raise ValueError('vf-clamp: avar version 2 fonts are not supported yet')
+    if 'VARC' in font:
+        raise ValueError('vf-clamp: fonts with a VARC table are not supported yet')
+
     limits = {}
     axes_by_tag = {ax.axisTag: ax for ax in font['fvar'].axes}
 
@@ -124,7 +170,7 @@ def vf_clamp_instantiate(file_options, axes_json):
     partial.save(file_options['output-file'])
 
 vf_clamp_instantiate
-`))),y}async function k(){return A||(A=l().then(e=>e.runPythonAsync(`
+`))),N}async function H(){return D||(D=d().then(e=>e.runPythonAsync(`
 from fontTools.ttLib import TTFont
 
 def vf_clamp_normalize_wght(file_options, new_min_str):
@@ -144,6 +190,10 @@ def vf_clamp_normalize_wght(file_options, new_min_str):
 
     old_min = wght_axis.minValue
     default = wght_axis.defaultValue
+    # With the default at the minimum there is no below-default range to stretch; leave the font as is.
+    if default <= old_min:
+        font.save(file_options['output-file'])
+        return 'skipped'
     scale = (default - new_min) / (default - old_min)
 
     def remap(v):
@@ -177,69 +227,16 @@ def vf_clamp_normalize_wght(file_options, new_min_str):
                     av.NominalValue = remap(av.NominalValue)
                     av.RangeMinValue = remap(av.RangeMinValue)
                     av.RangeMaxValue = remap(av.RangeMaxValue)
+                elif fmt == 4:
+                    for rec in getattr(av, 'AxisValueRecord', []) or []:
+                        if rec.AxisIndex == wght_idx:
+                            rec.Value = remap(rec.Value)
 
     font.save(file_options['output-file'])
+    return 'done'
 
 vf_clamp_normalize_wght
-`))),A}async function C(){return T||(T=l().then(e=>e.runPythonAsync(`
-from fontTools.ttLib import TTFont
-
-def vf_clamp_prune_stat(file_options):
-    font = TTFont(file_options['input-file'])
-
-    if 'STAT' not in font or 'fvar' not in font:
-        font.save(file_options['output-file'])
-        return
-
-    stat = font['STAT'].table
-    if not getattr(stat, 'DesignAxisRecord', None) or not stat.DesignAxisRecord.Axis:
-        font.save(file_options['output-file'])
-        return
-
-    fvar_tags = {ax.axisTag for ax in font['fvar'].axes}
-    stat_axes = list(stat.DesignAxisRecord.Axis)
-
-    # Map old STAT AxisIndex -> new index after pruning STAT axes that vanish from fvar.
-    surviving_indices = [i for i, ax in enumerate(stat_axes) if ax.AxisTag in fvar_tags]
-    if len(surviving_indices) == len(stat_axes):
-        # No axes removed — nothing to prune.
-        font.save(file_options['output-file'])
-        return
-    old_to_new = {old: new for new, old in enumerate(surviving_indices)}
-
-    # Rewrite the DesignAxisRecord.Axis list to surviving axes only.
-    stat.DesignAxisRecord.Axis = [stat_axes[i] for i in surviving_indices]
-    if hasattr(stat, 'DesignAxisCount'):
-        stat.DesignAxisCount = len(stat.DesignAxisRecord.Axis)
-
-    # Prune AxisValueArray entries that reference removed axes.
-    if stat.AxisValueArray and stat.AxisValueArray.AxisValue:
-        kept = []
-        for av in stat.AxisValueArray.AxisValue:
-            fmt = av.Format
-            if fmt in (1, 2, 3):
-                if av.AxisIndex not in old_to_new:
-                    continue  # references a removed axis
-                av.AxisIndex = old_to_new[av.AxisIndex]
-                kept.append(av)
-            elif fmt == 4:
-                inner = list(getattr(av, 'AxisValueRecord', []) or [])
-                if any(rec.AxisIndex not in old_to_new for rec in inner):
-                    continue  # whole record dies if any inner ref is dead
-                for rec in inner:
-                    rec.AxisIndex = old_to_new[rec.AxisIndex]
-                kept.append(av)
-            else:
-                # Unknown format — keep as-is to be safe.
-                kept.append(av)
-        stat.AxisValueArray.AxisValue = kept
-        if hasattr(stat, 'AxisValueCount'):
-            stat.AxisValueCount = len(kept)
-
-    font.save(file_options['output-file'])
-
-vf_clamp_prune_stat
-`))),T}async function $(){return b||(b=l().then(e=>e.runPythonAsync(`
+`))),D}async function J(){return O||(O=d().then(e=>e.runPythonAsync(`
 from fontTools.ttLib import TTFont
 
 def vf_clamp_update_os2(file_options):
@@ -250,25 +247,26 @@ def vf_clamp_update_os2(file_options):
         return
 
     wght_axis = next((ax for ax in font['fvar'].axes if ax.axisTag == 'wght'), None)
-    if wght_axis is None:
+    if wght_axis is not None:
+        # OS/2.usWeightClass valid range is 1..1000.
+        weight_class = int(round(max(1, min(1000, wght_axis.defaultValue))))
+    elif 'OS/2' in font:
+        # wght was pinned: fontTools has already set usWeightClass to the pinned weight.
+        weight_class = font['OS/2'].usWeightClass
+    else:
         font.save(file_options['output-file'])
         return
 
-    new_default = wght_axis.defaultValue
-    # OS/2.usWeightClass valid range is 1..1000.
-    weight_class = int(round(max(1, min(1000, new_default))))
-
     if 'OS/2' in font:
         os2 = font['OS/2']
         os2.usWeightClass = weight_class
-        # fsSelection bits: 0x20 = BOLD, 0x40 = REGULAR.
-        # Mirror the convention: REGULAR when usWeightClass < 600, BOLD when >= 700.
+        # fsSelection: 0x01 ITALIC (kept), 0x20 BOLD, 0x40 REGULAR. REGULAR only when neither ITALIC nor BOLD.
         fs = os2.fsSelection
         fs &= ~(0x20 | 0x40)
         if weight_class >= 700:
-            fs |= 0x20  # BOLD
-        elif weight_class < 600:
-            fs |= 0x40  # REGULAR
+            fs |= 0x20
+        elif not fs & 0x01:
+            fs |= 0x40
         os2.fsSelection = fs
 
     if 'head' in font:
@@ -284,4 +282,4 @@ def vf_clamp_update_os2(file_options):
     font.save(file_options['output-file'])
 
 vf_clamp_update_os2
-`))),b}function z(e){return e.replace(/[^A-Za-z0-9 -]/g,"").trim().split(/\s+/).join("-").replace(/^-+|-+$/g,"").slice(0,63)}async function W(e,o){if(!o)return e;const a=await l(),t=new u({pyodide:a}),n=new u({pyodide:a});try{const i=z(o);await t.upload(e);const r=new Map([["input-file",t.filename],["output-file",n.filename],["family-name",o],["postscript-name",i]]);return(await M())(r),n.download()}catch(i){return console.warn(`vf-clamp: name table patching failed for "${o}" — returning unpatched buffer`,i),e}finally{try{t.delete()}catch{}try{n.delete()}catch{}}}function q(e){return typeof e=="number"?e:e===null?null:[e.min,e.max]}async function B(e,o){const a=await l(),t=new u({pyodide:a}),n=new u({pyodide:a});try{await t.upload(e);const i=new Map([["input-file",t.filename],["output-file",n.filename]]);return(await U())(i,JSON.stringify(o)),n.download()}finally{try{t.delete()}catch{}try{n.delete()}catch{}}}async function E(e){const o=await l(),a=new u({pyodide:o}),t=new u({pyodide:o});try{await a.upload(e);const n=new Map([["input-file",a.filename],["output-file",t.filename]]);return(await C())(n),t.download()}catch(n){return console.warn("vf-clamp: STAT prune failed — returning unpruned buffer",n),e}finally{try{a.delete()}catch{}try{t.delete()}catch{}}}async function G(e){const o=await l(),a=new u({pyodide:o}),t=new u({pyodide:o});try{await a.upload(e);const n=new Map([["input-file",a.filename],["output-file",t.filename]]);return(await $())(n),t.download()}catch(n){return console.warn("vf-clamp: OS/2 + macStyle update failed — returning original buffer",n),e}finally{try{a.delete()}catch{}try{t.delete()}catch{}}}async function J(e,o){const a=await l(),t=new u({pyodide:a}),n=new u({pyodide:a});try{await t.upload(e);const i=new Map([["input-file",t.filename],["output-file",n.filename]]);return(await k())(i,String(o)),n.download()}catch(i){return console.warn("vf-clamp: wght normalisation failed — returning unnormalised buffer",i),e}finally{try{t.delete()}catch{}try{n.delete()}catch{}}}function H(e,o){const a=new Map(o.map(i=>[i.name,i])),t={};for(const i of e){const r=a.get(i);if(!r)throw new Error(`Named instance "${i}" not found in font`);for(const[s,m]of Object.entries(r.coordinates))t[s]?(t[s].min=Math.min(t[s].min,m),t[s].max=Math.max(t[s].max,m)):t[s]={min:m,max:m}}const n={};for(const[i,{min:r,max:s}]of Object.entries(t))n[i]=r===s?r:{min:r,max:s};return n}async function Z(e,o){var s,m;if(o.outputs.length===0)return[];const a=e instanceof ArrayBuffer?new Uint8Array(e):e,t=o.format??"ttf";let n=[],i=[];if(o.outputs.some(f=>{var p;return(p=f.instances)==null?void 0:p.length})){const f=await R(a);n=f.instances,i=f.axes}const r=[];for(const f of o.outputs){let p={};(s=f.instances)!=null&&s.length&&(p=H(f.instances,n)),f.axes&&(p={...p,...f.axes});for(const d of i){const x=p[d.tag];if(x!=null&&typeof x=="object"){const _=x;if(d.default<_.min||d.default>_.max){const P=Math.max(_.min,Math.min(_.max,d.default));console.warn(`vf-clamp: axis "${d.tag}" default (${d.default}) is outside restricted range [${_.min}, ${_.max}] — will be clamped to ${P}`)}}}const F={};for(const[d,x]of Object.entries(p))x!==null&&(F[d]=q(x));const S=f.name??((m=f.instances)!=null&&m.length?f.instances.length===1?f.instances[0]:`${f.instances[0]}-${f.instances[f.instances.length-1]}`:"output");let c=await B(a,F);c=await E(c),o.normalizeWeightAxis&&(c=await J(c,100)),c=await G(c),c=await W(c,S),t==="woff2"?c=await D(c):t==="woff"&&(c=await I(c)),r.push({name:S,buffer:c,format:t})}return r}function K(e,o){if(e===o)return e;const a=e.split(" "),t=o.split(" ");let n=0;for(;n<a.length&&n<t.length&&a[n]===t[n];)n++;let i=0;for(;i<a.length-n&&i<t.length-n&&a[a.length-1-i]===t[t.length-1-i];)i++;const r=a.slice(0,n).join(" "),s=a.slice(n,a.length-(i||0)).join(" "),m=t.slice(n,t.length-(i||0)).join(" "),f=i>0?a.slice(a.length-i).join(" "):"",p=s&&m?`${s}-${m}`:s||m;return[r,p,f].filter(Boolean).join(" ")}exports.clampFont=Z;exports.compactName=K;exports.convertToWoff=I;exports.convertToWoff2=D;exports.getInstances=R;
+`))),O}function G(e){const a=e.normalize("NFKD").replace(/[\u0300-\u036f]/g,"").replace(/[^A-Za-z0-9 -]/g,"").trim().split(/\s+/).join("-").replace(/-+/g,"-").replace(/^-+|-+$/g,"");return a.length<=63?a:`${a.slice(0,56).replace(/-+$/,"")}-${k(e)}`}function k(e){let a=2166136261;for(const t of e)a^=t.codePointAt(0),a=Math.imul(a,16777619)>>>0;return a.toString(36).padStart(6,"0").slice(-6)}async function K(e,a){if(!a)return e;const t=await d(),n=new x({pyodide:t}),i=new x({pyodide:t});try{const o=G(a);await n.upload(e);const r=new Map([["input-file",n.filename],["output-file",i.filename],["family-name",a],["postscript-name",o],["postscript-suffix",k(a)]]);return(await z())(r),i.download()}catch(o){throw Object.assign(new Error(`vf-clamp: name table patching failed for "${a}"`),{cause:o})}finally{try{n.delete()}catch{}try{i.delete()}catch{}}}function Z(e){return typeof e=="number"?e:e===null?null:[e.min,e.max]}async function Q(e,a){const t=await d(),n=new x({pyodide:t}),i=new x({pyodide:t});try{await n.upload(e);const o=new Map([["input-file",n.filename],["output-file",i.filename]]);return(await q())(o,JSON.stringify(a)),i.download()}finally{try{n.delete()}catch{}try{i.delete()}catch{}}}async function X(e){const a=await d(),t=new x({pyodide:a}),n=new x({pyodide:a});try{await t.upload(e);const i=new Map([["input-file",t.filename],["output-file",n.filename]]);return(await J())(i),n.download()}catch(i){throw Object.assign(new Error("vf-clamp: OS/2 and macStyle update failed"),{cause:i})}finally{try{t.delete()}catch{}try{n.delete()}catch{}}}async function Y(e,a){const t=await d(),n=new x({pyodide:t}),i=new x({pyodide:t});try{await n.upload(e);const o=new Map([["input-file",n.filename],["output-file",i.filename]]);return(await H())(o,String(a))==="skipped"&&console.warn("vf-clamp: normalizeWeightAxis skipped: the weight default is the axis minimum, so there is no lower range to remap"),i.download()}catch(o){throw Object.assign(new Error("vf-clamp: wght normalisation failed"),{cause:o})}finally{try{n.delete()}catch{}try{i.delete()}catch{}}}function ee(e,a){const t={};for(const i of e){const o=T(i,a);for(const[r,s]of Object.entries(o.coordinates))t[r]?(t[r].min=Math.min(t[r].min,s),t[r].max=Math.max(t[r].max,s)):t[r]={min:s,max:s}}const n={};for(const[i,{min:o,max:r}]of Object.entries(t))n[i]=o===r?o:{min:o,max:r};return n}function te(e){return e.length>=4&&e[0]===79&&e[1]===84&&e[2]===84&&e[3]===79}async function ne(e,a){var h,y;if(a.outputs.length===0)return[];const t=e instanceof ArrayBuffer?new Uint8Array(e):e,n=a.format??"ttf",{instances:i,axes:o,family:r}=await M(t),s=[];for(const f of a.outputs){let l={};if((h=f.instances)!=null&&h.length&&(l=ee(f.instances,i)),f.axes&&(l={...l,...f.axes}),a.strict){const _=new Set((f.instances??[]).map(p=>T(p,i))),w=i.filter(p=>!_.has(p)&&o.every(b=>{const F=p.coordinates[b.tag]??b.default,v=l[b.tag];return v==null?!0:typeof v=="number"?F===v:F>=v.min&&F<=v.max})).map(p=>p.name);if(w.length)throw new Error(`vf-clamp: output "${f.name||(f.instances??[]).join(", ")||"axes-only"}" would include unselected instances (${w.join(", ")}); use planOutputs() to split the selection`)}for(const _ of o){const w=l[_.tag];if(w!=null&&typeof w=="object"){const p=w;if(_.default<p.min||_.default>p.max){const b=Math.max(p.min,Math.min(p.max,_.default));console.warn(`vf-clamp: axis "${_.tag}" default (${_.default}) is outside restricted range [${p.min}, ${p.max}] — will be clamped to ${b}`)}}}const c={};for(const[_,w]of Object.entries(l))w!==null&&(c[_]=Z(w));const u=(y=f.instances)!=null&&y.length?f.instances.length===1?f.instances[0]:`${f.instances[0]}-${f.instances[f.instances.length-1]}`:"Clamped",g=f.name||(r?`${r} ${u}`:u);let m=await Q(t,c);if(n==="otf"&&!te(m))throw new Error("vf-clamp: format 'otf' needs a CFF/CFF2 source font; this font has TrueType outlines — use 'ttf'");a.normalizeWeightAxis&&(m=await Y(m,100)),m=await X(m),m=await K(m,g),n==="woff2"?m=await L(m):n==="woff"&&(m=await $(m)),s.push({name:g,buffer:m,format:n})}return s}function R(e,a){const t={};for(const n of a){const i=e.map(o=>o.coordinates[n.tag]??n.default);t[n.tag]={min:Math.min(...i),max:Math.max(...i)}}return t}function j(e,a,t,n){return a.filter(i=>t.has(i)?!1:n.every(o=>{const r=i.coordinates[o.tag]??o.default,s=e[o.tag];return!s||r>=s.min&&r<=s.max}))}function ae(e){return e.reduce((a,t)=>!a||t.maximum-t.minimum>a.maximum-a.minimum?t:a,void 0)}function ie(e,a,t){const{axes:n,instances:i}=e,o=[...new Set(a)].map(l=>T(l,i));if(!o.length)return[];const r=new Set(o);let s;if(!j(R(o,n),i,r,n).length)s=[o];else{s=o.map(c=>[c]);let l=!0;for(;l;){l=!1;e:for(let c=0;c<s.length;c++)for(let u=c+1;u<s.length;u++){const g=[...s[c],...s[u]];if(!j(R(g,n),i,r,n).length){s[c]=g,s.splice(u,1),l=!0;break e}}}}const h=ae(n),y=h?[h,...n.filter(l=>l.tag!==h.tag)]:n,f=(l,c)=>{for(const u of y){const g=(l.coordinates[u.tag]??u.default)-(c.coordinates[u.tag]??u.default);if(g)return g}return 0};return s=s.map(l=>[...l].sort(f)).sort((l,c)=>f(l[0],c[0])),s.map(l=>{const c=l[0],u=l[l.length-1],g=l.length===1?c.name:C(c.name,u.name);return{name:t?`${t} ${g}`:g,instances:l.map(m=>m.name)}})}function oe(e,a){const t=a.map(n=>T(n,e.instances));return t.length?j(R(t,e.axes),e.instances,new Set(t),e.axes).map(n=>n.name):[]}exports.clampFont=ne;exports.compactName=C;exports.convertToWoff=$;exports.convertToWoff2=L;exports.getInstances=M;exports.planOutputs=ie;exports.unboughtInstances=oe;

package/dist/index.d.ts

@@ -52,9 +52,16 @@ export declare interface ClampOptions {
     /**
      * Output format — defaults to 'ttf'.
      * 'woff' and 'woff2' transcode the result to a web-compressed flavour.
-     * 'otf' is a passthrough — the instancer preserves the input outline format.
+     * 'otf' is a label, not a conversion — it requires a CFF/CFF2 source and throws for TrueType outlines.
      */
     format?: OutputFormat;
+    /**
+     * Refuse any output whose range would include a named instance that was not listed
+     * (e.g. Regular + Bold would also hand over Medium and SemiBold). Axes-only outputs list none,
+     * so they pass only if their range holds no named instance. Throws instead of clamping.
+     * Use planOutputs() to split a customer's selection into safe outputs. Defaults to false.
+     */
+    strict?: boolean;
     /**
      * Remap the wght axis so its minimum becomes 100, making CSS font-weight values
      * (100–900) work as expected. Instance and STAT axis value coordinates are
@@ -111,6 +118,8 @@ export declare interface FontInstancesResult {
     axes: AxisDefinition[];
     /** All named instances defined in the font */
     instances: FontInstance[];
+    /** The font's family name (typographic family, nameID 16, else nameID 1); used to name outputs that set no name */
+    family?: string;
 }
 
 /**
@@ -147,14 +156,40 @@ export declare interface OutputConfig {
 /**
  * Output format for clampFont() — defaults to 'ttf'.
  * 'woff' and 'woff2' transcode to web-compressed flavours.
- * 'otf' is a passthrough (no outline conversion); the instancer preserves the input flavour.
+ * 'otf' requires a CFF/CFF2 source (no outline conversion is done) and throws for TrueType outlines.
  */
 export declare type OutputFormat = 'ttf' | 'otf' | 'woff' | 'woff2';
 
 /** Pin an axis at a single value — the axis is locked and removed from the output font's design space */
 export declare type PinnedAxis = number;
 
+/**
+ * Groups a customer's selected named instances into clampFont outputs so that no output's range
+ * contains a named instance the customer did not select.
+ *
+ * Selections merge into one output only when their combined range holds no unselected named
+ * instance: Regular + Medium + SemiBold + Bold → one output; Regular + Bold alone → two outputs
+ * (each pinned to its own instance). Output names come from compactName(), optionally prefixed
+ * with `family`.
+ *
+ * @param font - The font's axes and named instances, from getInstances()
+ * @param selected - Names of the instances the customer bought (must match exactly)
+ * @param family - Optional family name to prefix each output name with, e.g. "Encode Sans"
+ * @returns OutputConfig entries ready for clampFont(), sorted along the primary axis
+ * @throws If a selected name is not a named instance of the font, or names more than one (ambiguous)
+ */
+export declare function planOutputs(font: FontInstancesResult, selected: string[], family?: string): OutputConfig[];
+
 /** @deprecated Use OutputConfig instead */
 export declare type SubfamilyConfig = OutputConfig;
 
+/**
+ * Lists the named instances that a single output built from `names` would include without being selected,
+ * e.g. ['Medium', 'SemiBold'] for Regular + Bold. An empty array means the output is purchase-safe.
+ *
+ * @param font - The font's axes and named instances, from getInstances()
+ * @param names - The instance names one output would hull
+ */
+export declare function unboughtInstances(font: FontInstancesResult, names: string[]): string[];
+
 export { }