IKEA assembly, step by step: animated, manual-style 3D guides. Scan any paper manual with Together AI.
TypeScript
/**
* Turns scripts/ikea/facts.json (from fetch.ts) into the catalog data the app ships.
*
* npm run ikea:build
*
* Writes src/data/ikea-rows.ts (products we can draw), ikea-names.ts (every IKEA family name and its
* types) and ikea-items.ts (article numbers per guide). scripts/ikea/slugs.json remembers every slug
* ever handed out, so a product keeps its link across runs and a slug is never reused.
* Hand made entries (CATALOG and ROWS) always win: IKEA products that match one only add their
* article numbers to it.
*/
import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
import path from "node:path";
import { BASE, baseSlug, type CatalogEntry } from "@/lib/catalog";
import { fold } from "@/lib/fold";
import { decodeRows, encodeRow, type IkeaRow } from "@/lib/ikea";
import { KIND_ARCH, ROWS, specFor, type Kind, type X } from "@/lib/products";
import { classify, type Draw, type Fact, type Hint } from "./classify";
import { asUk, usBedName } from "./us";
const DIR = import.meta.dirname;
const ROOT = path.resolve(DIR, "../..");
const DATA = path.join(ROOT, "src", "data");
const LOCK = path.join(DIR, "slugs.json");
const HEAD = "// Generated by scripts/ikea/build.ts from IKEA product data. Do not edit by hand.\n";
/* ---------- hints from the hand made rows ---------- */
function hintOf(e: CatalogEntry): X {
const x: X = {};
if (e.drawers) Object.assign(x, { rows: e.drawers.rows, cols: e.drawers.cols, knobs: e.drawers.knobs, plinth: e.drawers.plinth || undefined });
if (e.cabinet) Object.assign(x, { doors: e.cabinet.doors, shelves: e.cabinet.shelves, knobs: e.cabinet.handles });
if (e.table) Object.assign(x, { attach: e.table.attach, legs: e.table.legs, shelf: e.table.shelf });
if (e.bed) Object.assign(x, { m: e.bed.mattressW, f: e.bed.footH });
if (e.sofa) Object.assign(x, { seats: e.sofa.seats, arms: e.sofa.arms });
return x;
}
const HINTS = new Map<string, Hint>();
for (const [name, kind, , w, h, d, x] of ROWS) {
const k = fold(name) + "|" + kind;
if (!HINTS.has(k)) HINTS.set(k, { kind, x: x ?? {}, w, h, d });
}
for (const e of BASE) {
// hand-checked entries, as far as their kind draws the same way (LACK's TV bench is a table)
const kind = e.kind;
if (!kind || !e.checked || KIND_ARCH[kind] !== e.archetype) continue;
const k = fold(e.name) + "|" + kind;
if (!HINTS.has(k)) HINTS.set(k, { kind, x: hintOf(e), w: e.size.w, h: e.size.h, d: e.size.d });
}
/** Same family and kind first; otherwise any row of the family, for its knob style. */
function hints(family: string, kind: Kind): Hint | undefined {
const exact = HINTS.get(fold(family) + "|" + kind);
if (exact) return exact;
const arch = KIND_ARCH[kind];
for (const [k, hint] of HINTS) if (k.startsWith(fold(family) + "|") && KIND_ARCH[hint.kind] === arch && hint.x.knobs) return { ...hint, x: { knobs: hint.x.knobs } };
return undefined;
}
/* ---------- measurements from the product pages ---------- */
/**
* The measurements measure.ts read off product pages (measures.json, git ignored like facts.json), by the article
* number each page is for. Only that exact article counts, so what one build wrote never steers the next. Without
* the file, the listings' sizes are all there is.
*/
function pageMeasures(): Map<string, Record<string, string>> {
const out = new Map<string, Record<string, string>>();
const file = path.join(DIR, "measures.json");
if (!existsSync(file)) return out;
const pages: Record<string, { item: string; m: Record<string, string> }> = JSON.parse(readFileSync(file, "utf8"));
for (const page of Object.values(pages)) if (Object.keys(page.m).length) out.set(page.item, page.m);
return out;
}
const MEASURES = pageMeasures();
/** A product (or a group of its colours) with the measurements of the first of its articles that has a page. */
const measured = (f: Fact, items = f.items): Fact => {
const m = items.map((i) => MEASURES.get(i)).find(Boolean);
return m ? { ...f, m } : f;
};
/* ---------- matching against hand made entries ---------- */
const LATER_KINDS = new Set<Kind>(["office", "chaise", "corner", "cot", "bunk", "loft", "dropleaf", "daybed", "mixed", "sliding", "slidecab", "bookrow", "cabrow", "section", "gateleg", "washstand", "sinkcab", "appliance", "shoerack", "clothesrack", "changing", "divider", "backbench", "junior", "lounge", "highchair", "cornercab", "cornerrobe", "usofa", "lounger", "swivel", "conference", "cornerdesk", "conftable", "lidbox", "shelfbench", "workbench", "extension", "deskdraw", "boxdesk", "hatrack", "coatstand", "pouffe", "chairbed", "airer", "riser"]);
function baseMatch(name: string, draw: Draw): CatalogEntry | undefined {
const fam = fold(name);
const spec = specFor(draw.kind, name, "", draw.w, draw.h, draw.d, draw.x);
// sizes read off the product page count as unknown here, as they were before the page was read
const p = draw.paged;
const g = p ? { w: draw.guessed.w || p.w, h: draw.guessed.h || p.h, d: draw.guessed.d || p.d } : draw.guessed;
// a cube shelf with inserts or on an underframe is more than the hand made shelf of the same size, and a modular
// chest's drawers and open sections are its own
if (draw.x.ins || draw.x.uf || draw.x.mods || draw.own) return undefined;
for (const e of BASE) {
if (fold(e.name) !== fam) continue;
if (e.archetype !== spec.archetype && e.category !== spec.category) continue;
// the newer kinds draw a different shape from anything hand made in their archetype
if (LATER_KINDS.has(draw.kind) && e.category !== spec.category) continue;
// IKEA's own name for what it is sets it apart from a hand made entry of another category
if (draw.x.cat && e.category !== spec.category) continue;
// an open wall shelf is not the cabinet with a door of the same size
if (draw.kind === "wallshelf" && e.category === "Cabinet") continue;
if (draw.kind === "bed") {
if (e.bed?.mattressW === draw.x.m && (e.bed?.mattressL ?? 200) === (draw.x.l ?? 200)) return e;
continue;
}
if (g.w && g.h) {
// IKEA gives no size (most chairs and sofas): the same name and kind is the same product
if (e.category !== spec.category) continue;
if (spec.sofa && e.sofa && spec.sofa.seats !== e.sofa.seats) continue;
return e;
}
if (!g.w && Math.abs(e.size.w - draw.w) > 3) continue;
if (!g.h && Math.abs(e.size.h - draw.h) > 4) continue;
if (!g.d && Math.abs(e.size.d - draw.d) > 5) continue;
return e;
}
return undefined;
}
/* ---------- the US range ---------- */
/** Two drawings of one product: the same family and kind, and sizes within a few cm wherever both were measured. */
function sameDrawing(a: { name: string; draw: Draw }, name: string, draw: Draw) {
if (fold(a.name) !== fold(name)) return false;
// IKEA gives no size at all (most seats): a seat the family sells in the UK is the same one by its US name (a US
// "chair" can be the UK's easy chair)
const un = (dr: Draw, k: "w" | "h" | "d") => dr.guessed[k] || !!dr.paged?.[k];
const unsized = un(draw, "w") && un(draw, "h") && un(draw, "d");
const seating = (k: Kind) => KIND_ARCH[k] === "seat" || KIND_ARCH[k] === "sofa";
if (unsized && seating(a.draw.kind) && seating(draw.kind) && (a.draw.x.seats ?? 1) === (draw.x.seats ?? 1)) return true;
if (a.draw.kind !== draw.kind) return false;
// a bed or a cot is the same one for the same mattress (a crib's frame can be as long as a cot's)
if (draw.kind === "bed" || draw.kind === "cot") return Math.abs((a.draw.x.m ?? 0) - (draw.x.m ?? 0)) <= 3 && Math.abs((a.draw.x.l ?? 200) - (draw.x.l ?? 200)) <= 4;
const close = (k: "w" | "h" | "d", tol: number) => un(a.draw, k) || un(draw, k) || Math.abs(a.draw[k] - draw[k]) <= tol;
return close("w", 3) && close("h", 4) && close("d", 5) && (a.draw.x.seats ?? 0) === (draw.x.seats ?? 0);
}
/**
* US products the UK range doesn't have, read by the same rules: none of their article numbers is a UK one, and no
* UK or hand made guide draws the same family and kind at about the same size. Their own US type name stays as the
* start of the variant; the size is given in cm like every other.
*/
function usOnly(us: Fact[], gb: Fact[], groups: Map<string, { name: string; variant: string; draw: Draw; items: string[] }>) {
const gbItems = new Set(gb.flatMap((f) => f.items));
const uk = [...groups.values()];
const added: { name: string; variant: string; draw: Draw; items: string[] }[] = [];
const first = new Map<(typeof added)[number], Fact>();
const stats = { facts: us.length, shared: 0, drawable: 0, same: 0, added: 0, products: 0 };
for (const f of us) {
if (f.items.some((i) => gbItems.has(i))) {
stats.shared++;
continue;
}
const read = asUk(f);
const v = read ? classify(read, hints) : null;
if (!v || "skip" in v) continue;
stats.drawable++;
const bed = usBedName(f.size);
const draw: Draw = { ...v.draw, label: f.type.replace(/\s+/g, " ").trim(), ...(bed ? { size: `${bed}, ${v.draw.size}` } : {}), x: { ...v.draw.x, us: true } };
if (uk.some((g) => sameDrawing(g, f.name, draw)) || baseMatch(f.name, draw)) {
stats.same++;
continue;
}
// the same US product under a type spelled another way ("Sectional 4-seat" and "Sectional, 4-seat"), or in
// another colour: one row
const twin = added.find((g) => sameDrawing(g, f.name, draw) && JSON.stringify(g.draw.x) === JSON.stringify(draw.x));
stats.products++;
if (twin) {
twin.items.push(...f.items);
continue;
}
const variant = draw.size ? `${draw.label}, ${draw.size}` : draw.label;
const g = { name: f.name, variant, draw, items: [...f.items] };
groups.set(f.name + "|" + variant, g);
added.push(g);
first.set(g, f);
stats.added++;
}
// each product as its page measures it, as for the UK range
for (const g of added) {
const read = asUk(measured(first.get(g)!, g.items));
if (!read?.m) continue;
const v = classify(read, hints);
if (!("skip" in v)) g.draw = { ...g.draw, w: v.draw.w, h: v.draw.h, d: v.draw.d, guessed: v.draw.guessed, paged: v.draw.paged, x: { ...v.draw.x, us: true } };
}
return stats;
}
/** Without facts-us.json, the US rows and article numbers the last build wrote, as they were. */
function previousUs() {
const read = (file: string) => {
const p = path.join(DATA, file);
if (!existsSync(p)) return "";
const text = readFileSync(p, "utf8");
return text.slice(text.indexOf("`") + 1, text.lastIndexOf("`"));
};
const rows = decodeRows(read("ikea-rows.ts")).filter((r) => r.x.us);
const items = new Map<string, string[]>();
for (const line of read("ikea-items.ts").split("\n")) {
const [slug, list] = line.split("|");
if (list) items.set(slug, list.split(" "));
}
return rows.map((r) => ({ ...r, key: r.name + "|" + r.variant, items: items.get(r.slug ?? baseSlug(r.name, r.variant)) ?? [] }));
}
/* ---------- names ---------- */
const US_TYPES: Record<string, string> = {
dresser: "Chest of drawers", "shelf unit": "Shelf unit", nightstand: "Nightstand", loveseat: "Loveseat", sectional: "Sectional sofa", "tv unit": "TV unit",
"sleeper sofa": "Sofa-bed", "end table": "Side table", "dining table": "Dining table", "bar stool": "Bar stool", "office chair": "Office chair",
};
function namesIndex(facts: Fact[]) {
const fam = new Map<string, { name: string; types: Map<string, number> }>();
const add = (name: string, type: string, weight = 1) => {
const key = fold(name);
if (!/[a-z]{2}/.test(key)) return;
let e = fam.get(key);
if (!e) fam.set(key, (e = { name, types: new Map() }));
if (type) e.types.set(type, (e.types.get(type) ?? 0) + weight);
};
// a family's sets and combinations say less about what it is than its single pieces
const weight = (f: Fact) => (f.name.includes("/") || /\band\b|combination|\bcomb\b|set of|\+/i.test(f.type) ? 0.25 : 1);
for (const f of facts) for (const part of f.name.split(" / ")) add(part.trim(), f.type.replace(/[|;]/g, " ").trim(), weight(f));
const gb = new Set(fam.keys());
// US product pages add names that aren't sold in the UK. Their addresses spell Ä and Ö as "ae" and "oe".
const plain = (w: string) => w.replace(/ae/g, "a").replace(/oe/g, "o").replace(/ue/g, "u");
const types = new Map<string, string>();
for (const f of facts) types.set(fold(f.type), f.type);
for (const [k, v] of Object.entries(US_TYPES)) types.set(k, v);
const cache = path.join(DIR, "cache");
const files = existsSync(cache) ? readdirSync(cache).filter((f) => /^us-sitemap-\d+\.txt$/.test(f)) : [];
for (const file of files) {
for (const slug of readFileSync(path.join(cache, file), "utf8").split("\n")) {
const words = slug.split("-").slice(0, -1);
if (words.length < 2) continue;
let known = false;
for (let i = Math.min(3, words.length - 1); i >= 1 && !known; i--) {
const head = words.slice(0, i).join(" ");
known = gb.has(head) || gb.has(plain(head));
}
if (known) continue;
const rest = words.slice(1);
let type = "";
for (let j = Math.min(6, rest.length); j >= 1 && !type; j--) type = types.get(rest.slice(0, j).join(" ")) ?? "";
add(plain(words[0]).toUpperCase(), type, 0.5);
}
}
const out = [...fam.values()].map((e) => {
// the main type, and a second one when the family is about as often something else
const [first, second] = [...e.types.entries()].sort((a, b) => b[1] - a[1]);
const top = [first, second && second[1] >= 2 && second[1] * 2 >= first[1] ? second : undefined].filter((t) => t !== undefined).map((t) => t[0]);
return { name: e.name, line: top.length ? `${e.name}|${top.join(";")}` : e.name };
});
// without the US sitemaps in the cache, keep the US-only names the last build found
const known = path.join(DATA, "ikea-names.ts");
if (!files.length && existsSync(known)) {
const text = readFileSync(known, "utf8");
const body = text.slice(text.indexOf("`") + 1, text.lastIndexOf("`"));
for (const line of body.split("\n")) {
const name = line.split("|")[0];
if (!name || fam.has(fold(name))) continue;
fam.set(fold(name), { name, types: new Map() });
out.push({ name, line });
}
}
const lines = out.sort((a, b) => fold(a.name).localeCompare(fold(b.name))).map((e) => e.line);
return { lines, keys: [...fam.keys()], gb: gb.size, all: fam.size };
}
function lev(a: string, b: string) {
if (Math.abs(a.length - b.length) > 2) return 9;
const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
for (let j = 1; j <= b.length; j++) dp[0][j] = j;
for (let i = 1; i <= a.length; i++)
for (let j = 1; j <= b.length; j++) dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
return dp[a.length][b.length];
}
/**
* Real IKEA names we can't draw that search would otherwise read as a typo, or as the start, of one we
* can (MARKUS next to MARIUS). Only these ship with every page; the full names index loads on demand.
*/
function guardSet(realKeys: string[], drawable: string[]) {
const keys = new Set(drawable.map((n) => n.replace(/\s+/g, "")));
const words = new Set(drawable.flatMap((n) => n.split(" ")));
const out: string[] = [];
for (const real of realKeys) {
const k = real.replace(/\s+/g, "");
if (keys.has(k) || words.has(k)) continue;
let near = false;
if (k.length >= 4)
for (const n of keys) {
const dist = lev(k, n);
if (dist === 1 || (dist === 2 && k.length >= 6)) {
near = true;
break;
}
}
if (!near) for (const w of words) if (w.startsWith(k)) near = true;
if (near) out.push(k);
}
return out.sort();
}
/* ---------- main ---------- */
function main() {
const facts: Fact[] = JSON.parse(readFileSync(path.join(DIR, "facts.json"), "utf8")).products;
const groups = new Map<string, { name: string; variant: string; draw: Draw; items: string[] }>();
let drawable = 0;
const firstFact = new Map<string, Fact>();
for (const f of facts) {
const v = classify(f, hints);
if ("skip" in v) continue;
drawable++;
const variant = v.draw.size ? `${v.draw.label}, ${v.draw.size}` : v.draw.label;
const key = f.name + "|" + variant;
const g = groups.get(key);
if (g) g.items.push(...f.items);
else {
groups.set(key, { name: f.name, variant, draw: v.draw, items: [...f.items] });
firstFact.set(key, f);
}
}
// then each product as its page measures it, whichever of its colours the page was read for
for (const [key, g] of groups) {
const f = measured(firstFact.get(key)!, g.items);
if (!f.m) continue;
const v = classify(f, hints);
if (!("skip" in v)) g.draw = v.draw;
}
// the US range, kept apart in facts-us.json (fetch.ts --market us): only what the UK range doesn't have
const usFile = path.join(DIR, "facts-us.json");
const us = existsSync(usFile) ? usOnly(JSON.parse(readFileSync(usFile, "utf8")).products, facts, groups) : null;
const items = new Map<string, string[]>();
const attach = (slug: string, list: string[]) => items.set(slug, [...new Set([...(items.get(slug) ?? []), ...list])]);
const rows: (IkeaRow & { key: string; items: string[] })[] = [];
let merged = 0;
for (const [key, g] of groups) {
const hit = baseMatch(g.name, g.draw);
if (hit) {
attach(hit.slug, g.items);
merged++;
continue;
}
const { kind, x, w, h, d, kw } = g.draw;
rows.push({ key, name: g.name, kind, variant: g.variant, w, h, d, x, keywords: kw.length ? kw : undefined, items: g.items });
}
if (!us) rows.push(...previousUs());
rows.sort((a, b) => fold(a.name).localeCompare(fold(b.name)) || a.kind.localeCompare(b.kind) || a.w - b.w || a.h - b.h || a.d - b.d || a.variant.localeCompare(b.variant));
// the hand made slugs as they were when IKEA data first came in; check.ts holds them to it
const baseLock = path.join(DIR, "base-slugs.json");
if (!existsSync(baseLock)) writeFileSync(baseLock, JSON.stringify(Object.fromEntries(BASE.map((e) => [e.name + "|" + e.variant, e.slug])), null, 1) + "\n");
// slugs: keep every one handed out before, and never give a new product a slug that was used
const lock: Record<string, string> = existsSync(LOCK) ? JSON.parse(readFileSync(LOCK, "utf8")) : {};
const used = new Set(BASE.map((e) => e.slug));
for (const s of Object.values(lock)) {
if (used.has(s)) throw new Error(`slug ${s} in slugs.json is also a hand made slug`);
used.add(s);
}
for (const r of rows) {
let slug = lock[r.key];
if (!slug) {
const base = baseSlug(r.name, r.variant);
slug = base;
for (let i = 2; used.has(slug); i++) slug = `${base}-${i}`;
used.add(slug);
lock[r.key] = slug;
}
if (slug !== baseSlug(r.name, r.variant)) r.slug = slug;
attach(slug, r.items);
}
// a stored slug must not be the plain slug of an earlier row
const plain = new Set<string>();
for (const r of rows) {
const s = r.slug ?? baseSlug(r.name, r.variant);
if (plain.has(s)) throw new Error(`duplicate slug ${s}`);
plain.add(s);
}
const names = namesIndex(facts);
const itemLines = [...items.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([slug, list]) => `${slug}|${list.join(" ")}`);
const rowsText = rows.map((r) => encodeRow({ ...r, slug: r.slug })).join("\n");
writeFileSync(path.join(DATA, "ikea-rows.ts"), `${HEAD}// Rows we can draw, one per line: name|kind|variant|w|h|d|params|keywords|slug\nexport const IKEA_ROWS = \`${rowsText}\`;\n`);
writeFileSync(path.join(DATA, "ikea-names.ts"), `${HEAD}// Every IKEA family name with its main product types: NAME|type;type\nexport const IKEA_NAMES = \`${names.lines.join("\n")}\`;\n`);
writeFileSync(path.join(DATA, "ikea-items.ts"), `${HEAD}// Article numbers per guide: slug|number number\nexport const IKEA_ITEMS = \`${itemLines.join("\n")}\`;\n`);
const guard = guardSet(names.keys, [...BASE.map((e) => fold(e.name)), ...rows.map((r) => fold(r.name))]);
writeFileSync(path.join(DATA, "ikea-guard.ts"), `${HEAD}// Real IKEA names we can't draw that look like a typo of one we can (folded, no spaces)\nexport const IKEA_GUARD = "${guard.join(" ")}";\n`);
writeFileSync(LOCK, JSON.stringify(Object.fromEntries(Object.entries(lock).sort((a, b) => a[0].localeCompare(b[0]))), null, 1) + "\n");
const perKind: Record<string, number> = {};
for (const r of rows) perKind[r.kind] = (perKind[r.kind] ?? 0) + 1;
console.log(`${facts.length} IKEA products, ${drawable} drawable, ${groups.size} after merging colours`);
console.log(`${merged} match a hand made entry (article numbers added), ${rows.length} new rows`);
console.log(`names: ${names.gb} UK families, ${names.all} with US-only names, ${guard.length} guarded against typo matches`);
if (us) console.log(`US range: ${us.facts} products, ${us.shared} share an article number with the UK range, ${us.drawable} of the rest drawable, ${us.same} drawn as a UK product already, ${us.products} US-only products in ${us.added} new rows`);
else console.log(`US range: no facts-us.json, kept the ${rows.filter((r) => r.x.us).length} US-only rows of the last build`);
console.log(`article numbers: ${[...items.values()].reduce((s, l) => s + l.length, 0)} for ${items.size} guides`);
console.log(Object.entries(perKind).sort((a, b) => b[1] - a[1]).map(([k, c]) => `${k} ${c}`).join(", "));
}
main();